项目背景与目标

Meridian MCP 的核心目标是解决 AI Agent 在执行任务时的候选实体路由问题。传统的路由方案通常依赖预定义的查表或领域特定的规则引擎，而 Meridian 创新性地引入了轨道物理学隐喻：

将每个候选实体映射为天体系统中的一个天体（行星、卫星、特洛伊小行星、彗星等），通过物理特征向量自动分类，无需人工维护候选库。

版本信息： 当前稳定版本为 v3.2.0，发布于 2026-05-14，包含轨道分类器校准和热路径优化等改进。 资料来源：package.json

核心架构

Meridian MCP 采用分层架构设计，包含以下核心层次：

graph TD
    subgraph "接入层 Transport"
        A1[stdio 传输]
        A2[HTTP/Streamable 传输]
    end
    
    subgraph "MCP 协议层"
        B[MCP SDK]
    end
    
    subgraph "核心业务层"
        C[任务解析器]
        D[LLM 候选生成器]
        E[轨道分类器]
    end
    
    subgraph "外部依赖"
        F[GitHub Models<br/>Llama-3.3-70B]
    end
    
    A1 --> B
    A2 --> B
    B --> C
    C --> D
    D --> F
    F --> E
    E --> G[分类结果]

架构特点：

主要组件

MCP 核心模块

设计系统

Meridian 维护了一套完整的设计系统（Design System），确保多端视觉一致性：

graph LR
    subgraph "design-system/"
        A[tokens.css]
        B[preview/]
        C[ui_kits/]
        D[assets/]
    end
    
    subgraph "ui_kits/ 覆盖应用"
        L[landing]
        M[miniapp]
        H[helix]
        D1[docs]
        L1[lens]
        P[photon-router]
    end
    
    A --> L
    A --> M
    A --> H
    A --> D1
    A --> L1
    A --> P

Token 系统 包含以下核心变量：

资料来源：design-system/README.md

UI 套件

资料来源：design-system/ui_kits/landing/README.md、design-system/ui_kits/miniapp/README.md、design-system/ui_kits/helix/README.md

轨道分类器系统

物理特征向量

轨道分类器从候选实体的内容本身提取 9 维物理签名，无需查表：

资料来源：README.md

分类规则

基于提取的物理特征，六个分类评分规则决定最终天体类别：

score_planet    = min(mass, scope, independence)^1.5
score_moon      = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan    = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid  = 2.0 (基础分)
score_comet     = drag · cross_domain
score_irregular = max(fragmentation, 1 - coherence_time)

天体类别定义：

v3.2.0 分类器校准

2026-05-14 的更新重点改进了分类器死区问题：

• Moon/Comet/Irregular 脱离死区：原版分类器对这三类的评分区域存在重叠死区，导致部分合法候选被错误分类
• 长度偏差减少：降低了 mass 对分类结果的过度影响

资料来源：社区发布说明（见 v3.2.0 Release Notes）

部署与运行

安装方式

# 全局安装（推荐）
npm install -g meridian-orbital

# 或本地安装
npm install meridian-orbital

启动模式

资料来源：package.json:17-19

环境要求

关联项目

Meridian MCP 仓库采用 monorepo 结构，包含以下独立但相关的子项目：

Helio Mirror

天文数据镜像服务，将 Parker Solar Probe (PSP)、ISOIS、WISPR、JWST 等多源天文数据汇聚到 Hugging Face。

资料来源：helio-mirror/README.md

Finance MCP

基于 Cloudflare Workers 的金融 MCP 服务，集成了 WebAuthn 无密码认证（Passkey）和 Binance API。

资料来源：finance-mcp/README.md

Photon Route

文档路由引擎，作为 Meridian 路由能力的独立验证实现，提供与 qrouter 的对比基准。

# 示例文档结构
class Document:
    text: str           # 文档内容
    meta: dict          # 元数据（id, topic等）

# 预置测试语料库
_FIXTURE = [
    Document("photons travel through optical fibers...", meta={"id": "fixture-001"}),
    Document("superposition lets a quantum bit...", meta={"id": "fixture-002"}),
    # ...
]

资料来源：photon-route/src/photon_route/corpus.py

版本历史

注意： Issue #907 指出元数据一致性问题是当前的技术债务，包括版本号（3.1.0）、特征向量维度（25）和规范 URL 在 README.md、package.json、landing/docs/index.html 中的重复定义。建议通过 pre-commit 或 CI 检查来确保一致性。

运行测试

# 单元测试
npm test

# UI 测试（Playwright）
npm run test:ui

测试配置位于 tests/ui/playwright.config.mjs，依赖 Playwright 1.60.0+。

参见

• 设计系统详细文档 — Token 系统、UI 组件库、品牌资源
• Miniapp 使用指南 — 任务轨道交互界面
• Helix 蛋白质可视化 — 治疗性蛋白质推荐系统
• Helio 天文数据 — 多源天文数据镜像
• Finance MCP 部署 — 金融数据路由服务
• GitHub 仓库

1. 概述

轨道分类器（Orbital Classifier）是 Meridian MCP 的核心推理引擎，采用天体物理学类比的方式对候选路由条目进行分类排序。与传统基于规则或机器学习的路由系统不同，轨道分类器从候选内容的文本特征中提取 25 维物理签名，并将其映射为六个天体分类：planet（行星）、moon（卫星）、trojan（特洛伊小行星）、asteroid（小行星）、comet（彗星）、irregular（不规则天体）。

该分类器的设计目标包括：

• 领域无关性：候选条目可以是工具、提示词、文档、产品或任何可路由实体
• 自包含运行：分类器在进程内运行，无需外部依赖
• 确定性输出：相同输入总是产生相同分类结果
• 无监督特征提取：基于文本统计特征计算物理签名，不依赖预训练模型

版本说明：当前版本为 v3.2.0（2026-05-14），包含分类器校准改进，将 moon、comet、irregular 从"死区"中解放出来，并减少长度偏差。资料来源：package.json

系统架构

Meridian MCP 是一个基于轨道力学的任务路由系统，通过物理类比将候选对象分类为不同的天体类型（行星、卫星、特洛伊小行星、小行星、彗星、不规则体），实现领域无关的动态路由。本文档详细阐述该系统的整体架构、核心组件、数据流向以及部署模式。

概述

Meridian MCP 的数据流与反馈机制构成了一个闭环系统，将自然语言任务转化为天体物理学类别的候选项，并通过持续校准与在线学习不断优化分类精度。系统核心由三个阶段组成：任务输入 → LLM 候选生成 → 轨道分类器处理，最终输出带完整分类信息的排序结果。

本文档详细阐述该闭环系统的架构设计、数据流向、反馈收集机制以及分类器校准流程。

核心数据流架构

graph TD
    subgraph 输入层
        A[自然语言任务] --> B[route_task 工具调用]
    end
    
    subgraph 处理层
        B --> C[GitHub Models<br/>Llama-3.3-70B]
        C --> D[生成 N 个候选]
        D --> E[轨道分类器]
        E --> F[物理特征提取]
        F --> G[天体分类]
    end
    
    subgraph 输出层
        G --> H[排序候选项]
        H --> I[返回完整结果]
    end
    
    subgraph 反馈回路
        I --> J[结果使用追踪]
        J --> K[在线学习模块]
        K --> L[分类器微调]
        L --> E
    end
    
    subgraph 校准机制
        K --> M[校准脚本]
        M --> N[基准数据对比]
        N --> L
    end

数据流阶段详解

资料来源：README.md:核心流程概述

轨道分类器工作机制

物理特征向量

轨道分类器从每个候选项的纯内容中提取9 维物理特征向量，无需查表或预训练嵌入：

资料来源：README.md:物理特征提取

天体分类规则

系统通过六个分类规则计算得分，取 argmax 确定最终类别：

score_planet    = min(mass, scope, independence)^1.5
score_moon      = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan    = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid  = 2.0 · (mass < threshold && independence > threshold)
score_comet     = drag · cross_domain · fragmentation
score_irregular = fallback/default

资料来源：README.md:分类规则引擎

分类器校准 (v3.2.0)

v3.2.0 版本对分类器进行了重新校准，主要改进包括：

• Moon/Comet/Irregular 死区提升：将这些类别从分类死区中移出
• 长度偏差降低：减少候选文本长度对分类结果的影响
• 热路径优化：缩短分类推理延迟

校准数据基准存储于 scripts/calibration-baseline.json，可通过 scripts/calibrate-classifier.mjs 脚本验证分类精度变化。

资料来源：calibrate-classifier.mjs 脚本说明

在线学习与反馈机制

反馈收集架构

sequenceDiagram
    participant Client as 客户端代理
    participant MCP as MCP 服务器
    participant OLM as 在线学习模块
    participant Classifier as 轨道分类器
    
    Client->>MCP: route_task(task)
    MCP->>Client: 分类结果
    
    Note over Client: 结果被使用/采纳
    
    Client->>OLM: 反馈信号<br/>(采纳/拒绝/修正)
    OLM->>OLM: 更新内部状态
    OLM->>Classifier: 权重调整
    
    Note over OLM: 下次调用生效

在线学习模块

cf-worker/online_learning.mjs 实现了边缘计算环境下的在线学习能力：

资料来源：cf-worker/online_learning.mjs

反馈信号类型

模拟与验证流程

自动化模拟报告

系统通过 GitHub Actions 定期运行模拟验证，数据流状态变更后自动生成报告：

资料来源：data/sim-reports/README.md

模拟异常检测

观察连续两份模拟报告可发现漂移现象：

• recall@1 下降 → 分类边界可能偏移
• nDCG@5 崩溃 → 排序权重异常
• 分类分布异常 → 特征提取管道问题

# 本地运行模拟
# 参见 OPERATIONS.md → "Simulations" 章节

环境配置与数据流控制

关键环境变量

资料来源：README.md:环境变量配置

MCP 传输层与数据流

Stdio 传输模式

graph LR
    A[Claude/Cline] -->|stdio| B[meridian-mcp]
    B -->|stdout| A
    B <--> C[GitHub Models API]

适用于本地开发与 CLI 工具集成：

# 启动 stdio 模式
npm run stdio
# 或直接执行
node mcp/index.mjs

HTTP/Streamable 传输模式

graph LR
    A[Grok/ChatGPT] -->|HTTP| B[meridian-mcp-http]
    B -->|Streamable HTTP| A
    B <--> C[GitHub Models API]
    B <--> D[Cloudflare KV<br/>在线学习状态]

适用于远程部署与云端代理场景：

# 启动 HTTP 模式
npm run http
# 或直接执行
node mcp/http.mjs

资料来源：mcp/http.mjs:HTTP 传输实现

常见数据流问题与解决

分类结果与预期不符

症状：返回的候选项类别与任务语义不匹配

排查步骤：

1. 检查 scripts/calibration-baseline.json 是否过期
2. 运行 node scripts/calibrate-classifier.mjs 验证基准
3. 查看最新 orbital-*.txt 模拟报告的 recall@1 指标
4. 确认 coherence_time 特征是否异常（v3.1.0 新增）

解决方案：

• 执行分类器重校准流程
• 检查反馈信号是否被正确收集
• 验证 cross_domain 特征提取逻辑

在线学习未生效

症状：反馈后分类结果未见改善

排查步骤：

1. 确认 MERIDIAN_ENABLE_ONLINE_LEARNING=true
2. 检查 Cloudflare KV 连接状态
3. 验证 cf-worker/online_learning.mjs 日志输出
4. 确认反馈信号格式正确

数据一致性问题

背景：社区 issue #907 指出元数据（版本号、特征向量维度、URL）在多处重复存在，存在不一致风险。

受影响位置：

• README.md
• package.json
• landing/docs/index.html

建议：实现 pre-commit 或 CI 检查确保元数据同步。

性能基准

资料来源：README.md:版本对比

相关资源

• 分类器校准脚本 — 验证分类精度
• 在线学习模块 — 边缘学习实现
• 配置参考 — 完整环境变量列表
• 模拟报告 — 自动化测试结果

参见

• 轨道分类器原理 — 分类算法的数学推导
• MCP 协议集成 — 与 Claude/Grok 的连接配置
• 贡献指南 — 提交反馈改进建议

概述

Meridian-MCP 是一个自包含的 MCP（Model Context Protocol）实现，集成了轨道任务路由和在线学习分类器。项目支持多种部署模式，适用于不同的使用场景：

MCP 服务器部署

前置条件

• Node.js >= 20
• npm 或 yarn 包管理器
• GitHub Models API 访问权限（用于生成候选路由）

stdio 传输模式（本地部署）

stdio 模式适用于需要本地运行的 AI 工具集成，如 Claude Desktop、Cursor、Windsurf 等。

#### 安装步骤

# 克隆仓库
git clone https://github.com/LuuOW/meridian-mcp.git
cd meridian-mcp

# 安装依赖
npm install

# 全局安装 MCP 服务器
npm install -g

#### 配置 Claude Desktop

在 Claude Desktop 的 MCP 配置文件（~/.config/claude-desktop/claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "meridian-mcp": {
      "command": "node",
      "args": ["/path/to/meridian-mcp/mcp/index.mjs"]
    }
  }
}

#### 验证安装

# 测试 stdio 模式
npm run stdio

HTTP/Streamable 传输模式（远程部署）

HTTP 模式支持通过 RESTful API 调用 MCP 功能，适用于 Web 应用集成。

#### 启动 HTTP 服务器

# 使用 npm 脚本
npm run http

# 或直接运行
node mcp/http.mjs

服务器默认监听端口取决于环境配置，访问 GET / 返回服务状态信息。

#### API 端点

Docker 容器部署

项目提供了多阶段构建的 Dockerfile，支持容器化部署。

# 资料来源：Dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY mcp ./mcp
COPY package.json .
ENV NODE_ENV=production
CMD ["node", "mcp/index.mjs"]

#### 构建与运行

# 构建镜像
docker build -t meridian-mcp:latest .

# 运行 stdio 模式
docker run -it meridian-mcp:latest

# 运行 HTTP 模式
docker run -p 3000:3000 meridian-mcp:latest node mcp/http.mjs

Cloudflare Workers 部署

Finance MCP 部署

Finance MCP 是一个运行在 Cloudflare Workers 上的金融数据代理服务，集成了 WebAuthn 免密码认证。

#### 部署架构

graph TD
    A[用户浏览器] -->|WebAuthn| B[Cloudflare Workers]
    B -->|读取/写入| C[KV Storage]
    B -->|代理请求| D[Binance API]
    A -->|OAuth 授权| B
    
    subgraph Cloudflare Edge
        B
        C
    end

#### 前置条件

• Wrangler CLI (npm install -g wrangler)
• Cloudflare 账号
• Cloudflare KV 命名空间

#### 部署步骤

1. 安装依赖并配置 Wrangler

cd finance-mcp
npm install

1. 创建 KV 命名空间

npx wrangler kv namespace create VAULT_KV
npx wrangler kv namespace create VAULT_KV --preview

1. 配置 wrangler.toml

编辑 cf-worker/wrangler.toml：

name = "finance-vault"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "VAULT_KV"
id = "<your-production-namespace-id>"
preview_id = "<your-preview-namespace-id>"

1. 设置环境变量和密钥

# 设置公共源地址
npx wrangler secret put ORIGIN  # 例如 https://finance.ask-meridian.uk

# 设置管理员密钥
npx wrangler secret put ADMIN_SECRET

# 设置用户 ID
npx wrangler secret put USER_ID

# 设置 OAuth 客户端 ID
npx wrangler secret put OAUTH_CLIENT_ID

# 设置 OAuth 客户端密钥
npx wrangler secret put OAUTH_CLIENT_SECRET

# 设置 Binance API 密钥
npx wrangler secret put BINANCE_API_KEY
npx wrangler secret put BINANCE_SECRET_KEY

1. 部署到 Cloudflare

npx wrangler deploy

#### API 端点一览

#### OAuth 2.0 端点

服务实现了标准 OAuth 2.0 端点用于机器间认证：

# 获取授权
GET /authorize?client_id=<client>&redirect_uri=<uri>&response_type=code&scope=read

# 交换令牌
POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<uri>&client_id=<client>&code_verifier=<pkce>

Binance Proxy 部署

Binance Proxy 是一个轻量级代理服务，用于转发 Binance API 请求。

# 资料来源：binance-proxy/Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src ./src
EXPOSE 8080
CMD ["node", "src/index.js"]

#### 构建并运行

cd binance-proxy
docker build -t binance-proxy:latest .
docker run -p 8080:8080 \
  -e BINANCE_API_KEY=your_api_key \
  -e BINANCE_SECRET_KEY=your_secret_key \
  binance-proxy:latest

Python Photon Route 服务部署

Photon Route 是一个基于 FastAPI 的文档检索和排名服务。

依赖安装

cd photon-route
pip install -e .

运行服务

# 使用 uvicorn
uvicorn photon_route.http_server:app --host 0.0.0.0 --port 8000

# 或使用项目脚本
python -m photon_route.http_server

API 端点

#### 排名查询示例

curl "http://localhost:8000/rank?q=quantum+entanglement&top_k=5&backend=v1"

响应格式：

{
  "query": "quantum entanglement",
  "backend": "v1",
  "results": [
    {"rank": 1, "score": 0.95, "text": "qubits entangle across distant detectors", "meta": {"id": "fixture-005", "topic": "entanglement"}}
  ]
}

GitHub Actions 自动化部署

Helio Mirror 自动同步

项目使用 GitHub Actions 定时同步太阳物理学数据：

# 资料来源：.github/workflows/helio-mirror-pull.yml（由 helio-mirror/README.md 描述）
# 触发条件：每周按计划或手动触发
# 主要功能：拉取 PSP、SolO、WISPR、JWST 等航天器数据

#### 触发方式

# 通过 gh CLI 触发
gh workflow run helio-mirror-pull.yml -R LuuOW/meridian-mcp -f perihelion=E20

#### 必需的秘密变量

分类器健康检查

项目包含两个定时运行的分类器健康检查工作流：

环境变量配置

MCP 服务器环境变量

Finance MCP 环境变量

Helio Mirror 环境变量

部署检查清单

生产部署前验证

• [ ] Node.js 版本 >= 20
• [ ] 所有依赖已安装 (npm ci)
• [ ] 环境变量已正确配置
• [ ] Cloudflare KV 命名空间 ID 已更新
• [ ] 秘密变量已通过 wrangler secret put 设置
• [ ] Dockerfile 构建成功
• [ ] 本地测试通过 (npm run test)

安全检查项

• [ ] ADMIN_SECRET 使用强随机字符串
• [ ] OAuth 客户端密钥已安全存储
• [ ] Binance API 密钥限制 IP（如适用）
• [ ] CORS 配置适合目标域名
• [ ] WebAuthn RP_ID 与服务域名匹配

常见部署问题

问题：wrangler deploy 失败

症状：部署时报错 Error: Not logged in

解决方案：

# 重新登录 Cloudflare
npx wrangler login

# 或手动设置 API token
npx wrangler auth list

问题：KV 命名空间绑定失败

症状：KV binding "VAULT_KV" not found

解决方案：

# 确认命名空间已创建
npx wrangler kv:namespace list

# 更新 wrangler.toml 中的 id

问题：WebAuthn 注册链接无法访问

症状：访问 /register/:token 返回 404

解决方案：确认 ORIGIN 环境变量设置正确，且链接未过期（默认 1 小时）。

相关资源

• MCP 协议文档
• Cloudflare Workers 文档
• WebAuthn 规范
• OAuth 2.0 RFC 6749

参见

• 设计系统文档 - 前端资产部署
• 分类器技术文档 - 模型部署细节
• Helio Mirror 文档 - 科学数据同步

1. 项目架构概览

Meridian MCP 是一个基于 Model Context Protocol（MCP）的动态任务路由系统，采用轨道力学（orbital mechanics）隐喻来对候选任务进行分类和排序。项目采用 monorepo 结构，包含多个功能模块和应用表面。

graph TD
    subgraph "核心模块"
        MCP["mcp/ — MCP 服务器实现"]
        CLASSIFIER["orbital classifier — 轨道分类器"]
        LLM["LLM 候选生成 — Llama-3.3-70B"]
    end
    
    subgraph "应用表面"
        LANDING["landing/ — 营销页面"]
        MINIAPP["miniapp/ — 核心演示应用"]
        HELIX["helix/ — 蛋白质推荐系统"]
        LENS["lens/ — 视觉实验室"]
        PHOTON["photon-route/ — 量子路由文档"]
    end
    
    subgraph "设计系统"
        TOKENS["design-system/ — 视觉语言"]
        UIKITS["ui_kits/ — 各表面组件库"]
    end
    
    subgraph "辅助服务"
        FINANCE["finance-mcp/ — 金融保险库"]
        HELIO["helio-mirror/ — 太阳物理数据镜像"]
    end
    
    MCP --> CLASSIFIER
    LLM --> CLASSIFIER
    CLASSIFIER --> MINIAPP
    MINIAPP --> LANDING
    LANDING --> TOKENS
    TOKENS --> UIKITS

1.1 Monorepo 目录结构

资料来源：MONOREPO.md:1-50

meridian-mcp/
├── mcp/                    # MCP 协议核心实现
│   ├── index.mjs           # stdio 传输模式入口
│   └── http.mjs            # HTTP/Streamable 传输模式入口
├── landing/                # 营销落地页
├── miniapp/                # 核心任务路由演示应用
├── helix/                  # 治疗性蛋白质推荐系统
├── lens/                   # 视觉实验室 UI
├── photon-route/           # 量子路由文档与演示
├── finance-mcp/            # 金融数据 MCP 服务
├── helio-mirror/           # 太阳物理数据镜像
├── design-system/          # 设计系统与令牌
│   ├── tokens.css          # CSS 自定义属性
│   ├── preview/            # 49 个独立预览页面
│   └── ui_kits/            # 各表面组件库
├── scripts/                # 运维脚本集合
├── data/
│   └── sim-reports/        # 模拟运行报告
└── .github/workflows/      # CI/CD 工作流

2. 环境配置与依赖

2.1 系统要求

项目对运行环境有明确的要求规范，确保所有组件正常工作需要满足以下条件。

资料来源：package.json:18

2.2 环境变量配置

项目运行时需要配置多个环境变量，这些变量控制 LLM 调用、传输协议、安全认证等核心功能。

资料来源：README.md:45-52

2.3 核心依赖

项目依赖 @modelcontextprotocol/sdk 实现 MCP 协议通信，开发依赖包含 Playwright 用于 UI 测试。

资料来源：package.json:8-10

3. MCP 服务部署

3.1 Stdio 传输模式

Stdio 模式适用于本地开发、直接进程调用以及作为其他 MCP 客户端的集成后端。

# 安装依赖
npm install

# 启动 stdio 服务器
npm run stdio
# 或直接运行
node mcp/index.mjs

Stdio 模式通过标准输入输出进行 JSON-RPC 通信，适用于 Claude Desktop、Cursor、Windsurf 等支持 stdio MCP 的客户端。服务接收任务请求后，调用 GitHub Models 生成候选路由项。

资料来源：README.md:1-30

3.2 HTTP/Streamable 传输模式

HTTP 模式适用于需要远程访问、跨网络调用或作为微服务架构的一部分。服务默认绑定 0.0.0.0:3100，支持 OAuth 2.0 + PKCE 认证流程。

# 启动 HTTP 服务器
npm run http
# 或直接运行
node mcp/http.mjs

HTTP 端点提供标准 OAuth 2.0 授权码流程，客户端需要先完成授权获取访问令牌，然后使用 Bearer Token 调用 /mcp 端点。

sequenceDiagram
    participant C as 客户端
    participant S as MCP HTTP Server
    
    C->>S: GET /authorize?client_id=xxx&redirect_uri=xxx
    S-->>C: 授权页面
    C->>S: 用户完成认证
    S->>C: 302 重定向到 redirect_uri?code=xxx
    C->>S: POST /token (code, code_verifier)
    S-->>C: {access_token, expires_in}
    C->>S: POST /mcp (Authorization: Bearer xxx)
    S-->>C: JSON-RPC 响应

资料来源：finance-mcp/README.md:80-95

3.3 Finance MCP 部署（Cloudflare Workers）

Finance 模块部署在 Cloudflare Workers 平台，使用 Wrangler 进行配置和管理。

# 1. 安装依赖
npm install

# 2. 创建 KV 命名空间
npx wrangler kv namespace create VAULT_KV
npx wrangler kv namespace create VAULT_KV --preview

# 3. 将返回的两个命名空间 ID 粘贴到 wrangler.toml

# 4. 配置公开源和 RP_ID
# 编辑 wrangler.toml [vars] 部分

# 5. 设置密钥
npx wrangler secret put ADMIN_SECRET            # 管理密钥
npx wrangler secret put USER_ID                 # 用户标识
npx wrangler secret put OAUTH_CLIENT_ID          # OAuth 客户端 ID

资料来源：finance-mcp/README.md:95-110

4. 持续集成与模拟测试

4.1 模拟测试工作流

项目维护三个自动化模拟测试工作流，定期验证核心功能的正确性。所有模拟报告存储在 data/sim-reports/ 目录中。

资料来源：data/sim-reports/README.md:1-15

4.2 Orbital 模拟测试

Orbital 模拟测试验证轨道分类器的核心逻辑，测试用例覆盖行星（planet）、卫星（moon）、特洛伊（trojan）、小行星（asteroid）、彗星（comet）和不规则（irregular）六种分类。

graph LR
    A[输入任务] --> B[LLM 生成候选]
    B --> C[轨道特征提取]
    C --> D[分类器评分]
    D --> E{argmax 分类}
    E -->|mass/scope/independence| F[planet]
    E -->|parent + independence| G[moon]
    E -->|dep_ratio + fragmentation| H[asteroid]
    E -->|其他特征组合| I[trojan/comet/irregular]
    F --> J[验证报告]
    G --> J
    H --> J
    I --> J

模拟报告包含每次运行的完整标准输出，用于检测功能回归。运维人员应定期检查最新两份报告以识别漂移，例如 classOf 变更后 recall@1 下降，或语料库扩展后 nDCG@5 异常。

资料来源：scripts/simulate-ci-methods.mjs:1-100

4.3 本地运行模拟

所有模拟测试支持本地运行，便于开发人员在提交前验证更改。

# 查看 OPERATIONS.md 获取详细说明
# 触发 orbital 模拟
npm run test

# 或直接运行测试脚本
node --test tests/*.test.mjs

# 触发 UI 测试（需要 Playwright）
npm run test:ui

资料来源：package.json:22-24

5. Helio Mirror 太阳物理数据

5.1 数据源配置

Helio Mirror 模块从多个官方天文数据源定期拉取太阳物理数据。

资料来源：helio-mirror/README.md:1-30

5.2 工作流触发

# 通过 GitHub Actions UI 触发
# Actions → helio-mirror-pull → Run workflow → 选择 perihelion

# 或使用 gh CLI
gh workflow run helio-mirror-pull.yml \
  -R LuuOW/meridian-mcp \
  -f perihelion=E20

必需 GitHub 密钥：HF_TOKEN — 需要写权限的 Hugging Face 访问令牌。

资料来源：helio-mirror/README.md:35-45

6. 设计系统部署

6.1 运行时 CSS 注入

设计令牌（Design Tokens）已在所有在线表面上运行时注入，无需额外引入样式表即可使用。

资料来源：design-system/README.md:1-30

6.2 添加新表面流程

当项目扩展到新的前端表面时，应遵循以下工作流程确保设计一致性。

flowchart TD
    A[新表面开发] --> B{最接近的 ui_kits 是？}
    B -->|landing| C[复制 landing UI kit]
    B -->|miniapp| D[复制 miniapp UI kit]
    B -->|helix| E[复制 helix UI kit]
    C --> F[复制 tokens.css 到新表面 CSS]
    D --> F
    E --> F
    F --> G[优先使用命名令牌]
    G --> H{需要新令牌?}
    H -->|是| I[在 tokens.css 中定义]
    H -->|否| J[开发完成]
    I --> K[同步到所有 live 表面]
    K --> J

命名令牌示例：var(--shadow-card-hover)、var(--accent)、var(--grad-hero)。

资料来源：design-system/README.md:30-45

7. 审计与代码质量

7.1 审计脚本

项目提供审计脚本用于检查代码质量、安全漏洞和依赖健康。

# 运行审计
node scripts/audit.mjs

审计脚本检查项包括但不限于：依赖版本安全漏洞、未使用的依赖、代码风格一致性、文档完整性等。

资料来源：scripts/audit.mjs:1-50

7.2 CI 模拟方法

simulate-ci-methods.mjs 脚本模拟 CI 环境中的各种测试场景，确保本地开发与 CI 环境行为一致。

# 模拟完整 CI 流程
node scripts/simulate-ci-methods.mjs

此脚本对调试环境配置问题和理解 CI 工作流逻辑特别有用。

资料来源：scripts/simulate-ci-methods.mjs:1-100

8. 常见问题与故障排除

8.1 元数据不一致问题

问题描述：Issue #907 指出包版本（3.1.0）、特征向量维度（25）和规范 URL 在 README.md、package.json 和 landing/docs/index.html 之间重复，存在不一致风险。

建议措施：

1. 在 package.json 中维护单一真相源（Single Source of Truth）
2. 配置 pre-commit 钩子在提交前验证元数据一致性
3. 添加 CI 检查步骤，确保发布前所有文件同步

资料来源：community_context: #907

8.2 GitHub Token 缺失

症状：MERIDIAN_GITHUB_TOKEN 或 GITHUB_TOKEN 未设置时，MCP 服务无法生成候选路由。

解决方案：

# 设置环境变量
export MERIDIAN_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# 或在 .env 文件中配置
echo "MERIDIAN_GITHUB_TOKEN=ghp_xxxxxxxxxxxx" > .env

确保令牌具有 Models: read 权限范围，可在 GitHub Settings → Developer settings → Personal access tokens 中配置。

资料来源：README.md:45-48

8.3 模拟测试失败

症状：本地 npm run test 或 CI 工作流报告失败。

排查步骤：

1. 检查最新两份模拟报告：data/sim-reports/
2. 对比 recall@1 和 nDCG@5 指标
3. 如果在 classOf 修改后出现下降，检查分类器评分规则
4. 如果在语料库扩展后出现异常，检查特征向量计算

# 查看最新 orbital 模拟报告
ls -lt data/sim-reports/ | head -5
cat data/sim-reports/orbital-$(date +%Y-%m-%d).txt

资料来源：data/sim-reports/README.md:15-20

8.4 Cloudflare 部署失败

症状：wrangler deploy 失败或 KV 命名空间错误。

排查步骤：

1. 验证 wrangler.toml 中的 KV 命名空间 ID
2. 确保 npx wrangler kv namespace create VAULT_KV 执行成功
3. 检查所有必需密钥是否已设置：npx wrangler secret list

# 验证 KV 命名空间
npx wrangler kv:namespace list

# 验证密钥
npx wrangler secret list

资料来源：finance-mcp/README.md:95-105

9. 发布流程

9.1 版本管理

项目遵循语义化版本（Semantic Versioning），主版本号在 package.json 中维护。

{
  "name": "meridian-orbital",
  "version": "3.2.0",
  "description": "Self-contained MCP — orbital task router..."
}

9.2 发布检查清单

资料来源：OPERATIONS.md:1-50

10. 参考链接

扩展与定制开发

Meridian-MCP 是一个模块化的任务路由系统，支持通过多种方式进行扩展和定制开发。本页面详细介绍如何基于现有架构扩展功能，包括自定义 Skills、UI 组件定制、API 扩展以及与其他系统的集成模式。

概述

Meridian MCP 是一个自包含的 MCP（Model Context Protocol）实现，采用轨道力学隐喻进行动态任务路由。项目当前版本为 v3.2.0，发布于 2026 年 5 月 14 日，包含轨道分类器校准及两项热路径优化。

核心功能围绕 9 维物理特征向量构建：

• 质量（mass）：对数缩放的候选体长度 × 关键词计数
• 范围（scope）：作用域度量
• 独立性（independence）：独立性评分
• 跨域亲和度（cross_domain）：三个恒星系统间的令牌域熵
• 碎片化（fragmentation）：碎片化程度
• 阻力（drag）：阻力系数
• 依赖比（dep_ratio）：最大兄弟 Jaccard 相似度
• 拉格朗日势（lagrange_potential）：拉格朗日点势能
• 相干时间（coherence_time）：基于 g⁽¹⁾ 风格的候选体令牌流自相关

资料来源：README.md

版本体系结构

语义化版本规范

Meridian MCP 采用语义化版本（SemVer）规范，版本格式为 MAJOR.MINOR.PATCH：

当前主版本为 v3，表示项目已稳定运行并具备完整的功能集。

资料来源：package.json

版本演进历史

timeline
    title Meridian MCP 版本演进
    
    2026-05-14 : v3.2.0 发布
    2026-05-14 : 轨道分类器校准
    2026-05-14 : 热路径优化 × 2
    
    此前 : v3.1.0 发布
    v3.1.0 : 新增 coherence_time 特征
    v3.1.0 : 特征向量维度: 25 维

元数据一致性现状

当前元数据分布

Meridian MCP 的核心元数据分散在多个文件中，这种分布模式虽然便于各模块独立维护，但也带来了一致性维护的挑战。

graph TD
    A[元数据需求] --> B[版本号: 3.2.0]
    A --> C[特征向量维度: 25]
    A --> D[Canonical URLs]
    
    B --> E[README.md]
    B --> F[package.json]
    B --> G[landing/index.html]
    B --> H[landing/docs/index.html]
    
    C --> E
    C --> F
    C --> G
    
    D --> E
    D --> F
    D --> G
    D --> H
    
    style E fill:#ffcccc
    style F fill:#ccffcc
    style G fill:#ccccff
    style H fill:#ffffcc

已知问题：#907

社区议题 #907 指出当前元数据存在以下问题：

资料来源：社区议题 #907

元数据存储位置详解

#### package.json

{
  "name": "meridian-orbital",
  "version": "3.2.0",
  "description": "Self-contained MCP — orbital task router...",
  "mcpName": "io.github.LuuOW/meridian-mcp",
  "homepage": "https://ask-meridian.uk",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/LuuOW/meridian-mcp.git"
  },
  "bugs": {
    "url": "https://github.com/LuuOW/meridian-mcp/issues"
  }
}

package.json 是项目的主元数据源，包含 npm 包管理所需的所有标准字段。

资料来源：package.json

#### README.md

README 文档包含项目描述、功能特性和使用说明，其中特征向量维度和版本信息需要与 package.json 保持一致。

# Meridian MCP
<!-- 项目描述与功能说明 -->
<!-- 特征向量维度: 25 -->

资料来源：README.md

#### Landing Pages

资料来源：landing/index.html，landing/docs/index.html

推荐实践

单点真相原则

建议采用 package.json 作为唯一真相来源，其他文件通过自动化手段同步：

graph LR
    A[package.json] -->|CI/CD 同步| B[README.md]
    A -->|CI/CD 同步| C[landing/index.html]
    A -->|CI/CD 同步| D[landing/docs/index.html]
    
    style A fill:#90EE90

预提交钩子建议

为确保元数据一致性，建议实现预提交或 CI 检查：

// pre-commit hook 示例 (伪代码)
const packageVersion = readJson('package.json').version
const readmeVersion = extractVersion('README.md')

if (packageVersion !== readmeVersion) {
  console.error('❌ Version mismatch detected!')
  process.exit(1)
}

设计系统令牌

设计系统的 CSS 令牌通过 design-system/tokens.css 集中管理，确保视觉一致性：

完整令牌集 + 语义类型类现已注入每个活动表面的运行时 CSS

资料来源：design-system/README.md

发布流程

v3.2.0 发布要点

发布日期：2026-05-14

无需迁移，语义保持一致，分类数值略有改善。

发布检查清单

相关配置文件

引擎要求

{
  "engines": {
    "node": ">=20"
  }
}

依赖管理

资料来源：package.json

参见

• README 文档 — 项目完整说明
• package.json — npm 包配置
• CHANGELOG.md — 版本变更历史
• 设计系统文档 — 视觉令牌管理
• 社区议题 #907 — 元数据一致性改进建议

概览

Meridian 的前端组件体系由以下几个独立应用组成，每个应用都有其特定的功能定位：

所有前端应用共享同一套设计系统，包括 CSS 自定义属性、语义化类型类和动画关键帧。资料来源：design-system/README.md

架构概览

graph TB
    subgraph 设计系统层
        Tokens["tokens.css<br/>设计令牌"]
        Keyframes["@keyframes 动画"]
        TypeClasses[".t-* 类型类"]
    end
    
    subgraph 应用层
        Miniapp["Miniapp<br/>任务轨道"]
        Lens["Lens<br/>WebXR 视觉"]
        Helix["Helix<br/>蛋白推荐"]
        Landing["Landing<br/>营销页"]
    end
    
    subgraph 后端服务
        MCPServer["MCP Server<br/>mcp.ask-meridian.uk"]
        GitHubModels["GitHub Models<br/>Llama-3.3-70B"]
    end
    
    Tokens --> Miniapp
    Tokens --> Lens
    Tokens --> Helix
    Tokens --> Landing
    
    Miniapp --> MCPServer
    Lens --> MCPServer
    Helix --> MCPServer
    
    MCPServer --> GitHubModels

设计系统

设计令牌

设计系统采用 CSS 自定义属性（Custom Properties）集中管理所有视觉变量，确保跨应用的一致性。资料来源：design-system/tokens.css

#### 颜色系统

#### 天体分类颜色

每个天体分类（Planet/Moon/Trojan 等）都有对应的语义化颜色类：

资料来源：design-system/README.md

#### 类型系统

#### 动画关键帧

使用方式

所有运行时 CSS 文件已包含完整的设计令牌集，无需额外引入样式表：

<!-- 已注入 tokens + .t-* 类 -->
<link rel="stylesheet" href="landing/style.css">
<!-- 或直接使用设计系统 -->
<link rel="stylesheet" href="design-system/tokens.css">

Miniapp 组件

Miniapp 是 Meridian 的核心演示应用，用户输入任务描述后，系统调用 MCP 服务生成候选路由，并以天体轨道动画进行可视化呈现。资料来源：miniapp/index.html

组件结构

graph TD
    subgraph Miniapp
        Nav["Nav 导航栏"]
        AskCard["AskCard 输入卡片"]
        MetaBar["MetaBar 元信息栏"]
        MiniGalaxy["MiniGalaxy 轨道画布"]
        ResultsList["ResultsList 结果列表"]
        CandidatePanel["CandidatePanel 候选详情面板"]
    end
    
    AskCard -->|提交任务| MiniGalaxy
    MiniGalaxy -->|选择候选| ResultsList
    ResultsList -->|点击行| CandidatePanel
    MetaBar -->|配额/模型| AskCard

核心组件

#### Nav 导航栏

顶部固定导航栏，包含品牌标识、应用菜单、命令面板触发器和 GitHub 链接。资料来源：design-system/ui_kits/miniapp/README.md

主要元素：

• 品牌 Logo + 产品名称
• 应用切换下拉菜单
• Cmd+K 命令面板触发器
• GitHub 仓库链接
• 移动端汉堡菜单

#### AskCard 输入卡片

核心输入组件，带有旋转霓虹环框架。资料来源：miniapp/miniapp.css

样式特点：

• 旋转霓虹环动画（neonRotate）
• 聚焦时边框高亮
• 示例芯片点击填充输入框

#### MiniGalaxy 轨道画布

将候选路由以天体轨道形式进行 3D 可视化的核心组件。资料来源：miniapp/mini-galaxy.js

功能：

• Canvas 2D/3D 渲染模式
• 候选天体围绕恒星系统旋转
• 点击天体查看详情
• 轨道位置基于分类得分计算

关键参数：

#### ResultsList 结果列表

候选结果列表视图，支持排序和筛选。资料来源：miniapp/app.js

#### CandidatePanel 候选详情面板

右侧滑入面板，展示完整候选信息。资料来源：design-system/ui_kits/miniapp/README.md

内容结构：

• 天体分类图标
• 标题与元信息
• 得分分解图表
• 决策规则说明
• Markdown 格式的详细描述
• 操作按钮（选择/复制/分享）

状态流转

stateDiagram-v2
    [*] --> Empty: 页面加载
    Empty --> Loading: 输入任务并提交
    Loading --> Results: 获取候选结果
    Results --> Empty: 清除搜索
    Results --> Candidate: 点击候选行
    Candidate --> Results: 关闭面板
    Loading --> Error: 请求失败
    Error --> Empty: 重试或取消

API 调用流程

sequenceDiagram
    participant User as 用户
    participant App as Miniapp
    participant MCP as MCP Server
    participant LLM as GitHub Models

    User->>App: 输入任务描述
    App->>MCP: POST /v1/route
    MCP->>LLM: Llama-3.3-70B 生成候选
    LLM-->>MCP: N 个候选路由条目
    MCP->>MCP: 轨道分类器计算
    MCP-->>App: 分类结果 + 得分
    App->>App: 渲染轨道动画
    App-->>User: 显示结果

Lens 组件

Lens 是 WebXR 视觉实验室应用，接收 AR 头显捕获的画面帧，处理后以天体系统形式呈现视野中的实体。资料来源：lens/index.html

组件结构

处理流程

graph LR
    A[AR 头显帧] --> B[POST /v1/vision]
    B --> C[GPT-4o-mini 处理]
    C --> D[轨道分类器]
    D --> E[3D 天体可视化]
    E --> F[锚定在视野中的恒星系统]

样式特点

Lens 应用保持了特有的深色主题和青/靛蓝配色方案，同时使用了设计系统的基础令牌。资料来源：lens/lens.css

Helix 组件

Helix 是治疗性蛋白推荐器界面，将推荐结果以恒星系统形式展示，每个蛋白质对应一个独立的星体世界。资料来源：helix/index.html

组件结构

可视化特点

• 垂直滚动宇宙界面
• 每张卡片代表一个推荐蛋白质
• 中心恒星：蛋白质本体
• 轨道上的化合物：真实配体名称（TrkA、p75、NGF-β、EGFR 等）
• 动画 SVG 化合物在虚线轨道上漂移

资料来源：helix/helix.css

输入组件

<!-- 垂直滚动界面中的固定输入卡片 -->
<div class="input-card">
  <textarea placeholder="描述蛋白质需求..."></textarea>
  <input type="file" accept="image/*" capture="environment">
  <button class="recommend-cta">Recommend</button>
</div>

Landing 页面组件

营销落地页组件库，包含完整的销售漏斗组件。资料来源：landing/index.html

组件清单

Hero 组件

英雄区是 Landing 页面的核心视觉元素，包含：

• Eyebrow 标签
• 主标题（渐变文字）
• 副标题说明
• 双 CTA 按钮
• 背景轨道 SVG 动画（SMIL <animateTransform>）

交互效果：

// 鼠标移动控制光晕位置
document.addEventListener('mousemove', (e) => {
  document.documentElement.style.setProperty('--cursor-x', e.clientX + 'px')
  document.documentElement.style.setProperty('--cursor-y', e.clientY + 'px')
})

资料来源：landing/style.css

特色悬停效果

FeaturesGrid 卡片使用霓虹环悬停效果：

.feature-card:hover {
  box-shadow: 0 0 20px var(--accent),
              0 0 40px var(--accent),
              0 0 60px var(--accent);
}

Photon-Route 组件

光子路由文档与演示界面，基于量子主题的路由系统可视化。资料来源：photon-route/pages/index.html

界面结构

• 单页索引布局
• 量子主题配色（青色/靛蓝）
• 文档内容区
• 交互式路由演示

样式复用模式

CSS 变量优先

所有组件应优先使用设计系统中的命名令牌：

/* 推荐 */
.card {
  background: var(--bg-surface);
  box-shadow: var(--shadow-card);
  color: var(--text-primary);
}

/* 避免 */
.card {
  background: #1a1a2e;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
  color: #e0e0e0;
}

组件分层

graph BT
    Layer1["tokens.css<br/>层级 1: 设计令牌"]
    Layer2["app.css<br/>层级 2: 布局与结构"]
    Layer3["components.css<br/>层级 3: 组件样式"]
    Layer4["utilities.css<br/>层级 4: 工具类"]
    
    Layer1 --> Layer2
    Layer2 --> Layer3
    Layer3 --> Layer4

响应式断点

常见问题与注意事项

状态同步

在单页应用状态管理中，注意以下状态转换的正确处理：

1. 加载状态：显示骨架屏或旋转动画
2. 空状态：显示友好提示和示例
3. 错误状态：提供重试选项
4. 结果状态：确保列表和可视化同步

性能考虑

无障碍性

• 所有交互元素需要有适当的 aria-label
• 颜色对比度需符合 WCAG 2.1 AA 标准
• 动画需尊重 prefers-reduced-motion 媒体查询

相关资源

• 设计系统文档
• MCP 服务器架构
• 轨道分类器原理
• API 端点参考

参考链接

• Miniapp 在线演示
• Lens WebXR 应用
• Helix 蛋白推荐器
• Photon-Route 文档

概述

Meridian MCP 是一个基于 Model Context Protocol (MCP) 的动态任务路由系统，通过轨道力学类比实现领域无关的候选路由功能。该项目同时支持 stdio 传输 和 HTTP/Streamable 传输 两种协议接入方式，兼容 Grok、ChatGPT、Claude 等主流 AI 助手。

资料来源：package.json:1-45

核心架构

Meridian MCP 采用分层架构，核心组件包括：

graph TD
    subgraph "客户端层"
        A[AI 助手 / Agent]
        B[Web Miniapp]
        C[Vision Lab]
    end
    
    subgraph "传输层"
        D[Stdio Transport]
        E[HTTP/Streamable Transport]
    end
    
    subgraph "MCP 服务器"
        F[server.mjs]
        G[skills.mjs<br/>route_task 工具]
    end
    
    subgraph "业务逻辑层"
        H[轨道分类器<br/>Orbital Classifier]
        I[LLM 调用<br/>Llama-3.3-70B]
    end
    
    subgraph "外部依赖"
        J[GitHub Models API]
        K[KV 存储]
    end
    
    A --> D
    B --> E
    C --> E
    D --> F
    E --> F
    F --> G
    G --> H
    G --> I
    I --> J
    H --> K

资料来源：README.md:1-30

组件职责

资料来源：mcp/index.mjs, mcp/http.mjs

传输协议支持

Stdio 传输

Stdio 传输适用于本地进程通信场景，是 Claude Desktop、Cursor 等工具的标准集成方式。

入口点配置：

{
  "bin": {
    "meridian-mcp": "./mcp/index.mjs"
  }
}

使用方式：

# 直接运行（用于调试）
node mcp/index.mjs

# 在 MCP 客户端中配置
# 例如 Claude Desktop 的 settings.json:
{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/path/to/meridian-mcp/mcp/index.mjs"],
      "env": {
        "MERIDIAN_GITHUB_TOKEN": "your-token"
      }
    }
  }
}

资料来源：package.json:10-14

HTTP/Streamable 传输

HTTP 传输支持远程部署和跨网络调用，适用于 Web Miniapp、Vision Lab 等前端应用。

入口点配置：

{
  "bin": {
    "meridian-mcp-http": "./mcp/http.mjs"
  }
}

运行方式：

node mcp/http.mjs

端点结构：

资料来源：README.md:1-30, mcp/http.mjs

工具定义

route_task 工具

route_task 是 Meridian MCP 提供的唯一核心工具，负责接收自然语言任务并返回排序后的候选路由列表。

输入参数：

处理流程：

graph TD
    A["route_task(task, limit)"] --> B["LLM 生成候选<br/>Llama-3.3-70B<br/>GitHub Models"]
    B --> C["轨道分类器处理"]
    C --> D["提取物理特征<br/>mass, scope, independence<br/>cross_domain, fragmentation..."]
    D --> E["计算天体分类<br/>planet | moon | trojan<br/>asteroid | comet | irregular"]
    E --> F["在线学习加权<br/>sigmoid gating<br/>v2 权重系统"]
    F --> G["返回排序候选"]
    
    style B fill:#e1f5fe
    style E fill:#fff3e0
    style G fill:#e8f5e9

输出结构：

{
  candidates: [
    {
      id: string,
      text: string,           // 完整 markdown 正文
      classification: {
        bodyClass: "planet" | "moon" | "trojan" | "asteroid" | "comet" | "irregular",
        starSystem: "forge" | "signal" | "mind",
        physics: {
          mass: number,
          scope: number,
          independence: number,
          // ... 25 维特征向量
        }
      },
      ranking: {
        score: number,
        position: number
      }
    }
  ],
  metadata: {
    model: string,
    version: string,
    processingTime: number
  }
}

资料来源：src/skills.mjs, README.md:10-35

配置选项

环境变量

资料来源：package.json:15-25, README.md:40-55

分类器参数

资料来源：README.md:1-30

认证机制

Stdio 模式

Stdio 传输不涉及网络认证，依赖进程环境变量传递令牌。

HTTP 模式 OAuth 2.1 + PKCE

HTTP 端点采用 OAuth 2.1 规范，支持 PKCE（Proof Key for Code Exchange）流程：

sequenceDiagram
    participant C as 客户端
    participant A as 授权服务器
    participant M as MCP 服务器
    
    C->>A: GET /authorize?client_id=xxx&code_challenge=yyy
    A-->>C: 返回 Passkey 登录页面
    C->>A: 完成 Passkey 验证
    A->>C: 302 /authorize/complete?code=zzz
    C->>A: POST /token (code, code_verifier)
    A-->>C: {access_token, refresh_token}
    C->>M: POST /mcp (Authorization: Bearer xxx)
    M-->>C: MCP JSON-RPC 响应

资料来源：finance-mcp/README.md

OAuth 端点：

资料来源：finance-mcp/src/index.ts:1-80

Bearer Token 模式

Node.js 二进制调用使用简化 Bearer Token 认证：

curl -X POST https://mcp.ask-meridian.uk/mcp \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"route_task","arguments":{"task":"帮我分析销售数据"}}}'

资料来源：README.md:60-70

客户端集成

Claude Desktop

在 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/absolute/path/to/meridian-mcp/mcp/index.mjs"],
      "env": {
        "MERIDIAN_GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
        "MERIDIAN_CANDIDATES": "5"
      }
    }
  }
}

Cursor

在 Cursor 设置的 MCP Server 配置中添加相同配置。

Windsurf

使用 MCP 通用配置方式，指向 stdio 入口。

Web Miniapp

Web 前端通过 HTTP 端点直接调用：

const response = await fetch('https://mcp.ask-meridian.uk/v1/route', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // OAuth Bearer Token 或其他认证
  },
  body: JSON.stringify({
    task: '帮我规划下周的会议安排',
    limit: 5
  })
});

const { candidates } = await response.json();

资料来源：README.md:70-90

版本演进

资料来源：README.md:100-120

常见问题

元数据一致性问题

Issue #907: 当前版本号 (3.1.0)、特征向量维度 (25)、规范 URL 等元数据在 README.md、package.json、landing/docs/index.html 中重复定义，存在不一致风险。

建议：使用 CI 检查或 pre-commit hook 验证元数据同步。

资料来源：社区讨论 #907

处理时间

典型调用耗时 5-15 秒，包含：

• GitHub Models API 调用（Llama-3.3-70B 推理）
• 本地轨道分类器处理
• KV 读写（在线学习权重更新）

资料来源：README.md:45-50

冷启动

分类器权重初始化为 w = 0，门控乘数 = 1，此时为纯启发式排名。部署第一天无需任何训练数据即可工作。

资料来源：README.md:1-30

相关资源

另请参阅

• 轨道分类器 — 深入了解 25 维特征向量与在线学习机制
• 设计系统 — Meridian 视觉语言与 UI 组件
• Helio 镜像 — 天体物理数据 MCP 集成

Pitfall Log / 踩坑日志

项目：luuow/meridian-mcp

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 meridian-mcp 与安装入口 meridian-skills-mcp 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx meridian-skills-mcp
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | repo=meridian-mcp; install=meridian-skills-mcp

2. 配置坑 · 来源证据：Automate metadata consistency (version, feature-vector dims, URLs)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Automate metadata consistency (version, feature-vector dims, URLs)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_00bb9cc4973344808616920b3eb5c648 | https://github.com/LuuOW/meridian-mcp/issues/907 | 来源类型 github_issue 暴露的待验证使用条件。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | release_recency=unknown