使用说明

mcp规范

MCP服务器，让AI助手完全访问您的特殊轨道项目——规格、人物角色、内存、作业、分析等等。

适用于任何兼容MCP的客户端：Claude Code、Claude Desktop、Cursor、Windsurf、Codex CLI等。

npm install -g specrails-mcp

快速开始

1.添加到您的MCP客户端

克劳德代码 (~/.claude/settings.json):

{
  "mcpServers": {
    "specrails": {
      "command": "specrails-mcp",
      "args": [],
      "env": {
        "SPECRAILS_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "specrails": {
      "command": "npx",
      "args": ["-y", "specrails-mcp"],
      "env": {
        "SPECRAILS_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

2.与您的AI助手交谈

You: "What projects do I have in specrails?"
AI:  → calls list_projects → shows your registered projects

You: "Run a health-check on DeckDex"
AI:  → calls enqueue_job with command "health-check" → job starts

You: "How much have I spent in the last 7 days?"
AI:  → calls get_analytics with period "7d" → shows cost breakdown

就是这样。人工智能通过MCP自动发现可用的工具和资源。

工具

你的AI助手可以调用的八种工具：

核心

工具	说明
`doctor`	对您的specrails安装进行健康检查。验证目录、配置文件和提供程序设置。

Hub--查询

工具	说明
`hub_status`	集线器服务器是否正在运行？注册了多少个项目？
`list_projects`	列出在specrails hub中注册的所有项目。
`get_project`	获取特定项目的详细信息（路径、提供者、时间戳）。
`get_jobs`	列出项目的作业。按状态筛选(`running`, `success`, `failed`, `cancelled`).支持分页。
`get_job_detail`	特定作业的完整细节——阶段、事件日志、令牌、成本、退出代码。
`get_analytics`	成本、作业数量、成功率、令牌使用情况。将范围扩展到项目或获得中心范围的聚合。时期： `7d`, `30d`, `all`.

Hub--行动

工具	说明
`enqueue_job`	在项目中排队新的AI作业。要求集线器服务器正在运行。支持模型覆盖。

`enqueue_job` 参数

参数	必填	说明
`projectId`	是	项目ID（从获取 `list_projects`)
`command`	是	运行命令（见下文）
`model`	否	覆盖AI模型（例如。， `"claude-opus-4-6"`)

已知命令

命令	它的作用
`implement`	实施特定的票证（例如。， `"implement #42"`)
`health-check`	审核项目的健康状况
`product-backlog`	为项目的产品待办列表生成/更新GitHub问题
`update-product-driven-backlog`	刷新产品驱动的待办事项列表

资源

您的AI助手可以通过MCP资源URI访问只读数据。

项目资源（specrails核心）

从本地项目目录读取：

URI	描述
`specrails://specs/{name}`	OpenSpec规范文件（YAML、JSON、Markdown）
`specrails://changes/{name}`	OpenSpec变更记录
`specrails://config/openspec`	项目配置(`openspec/config.yaml`)
`specrails://config/instructions`	代理指令文件(`CLAUDE.md` 或 `CODEX.md`，自动检测）
`specrails://personas/{name}`	VPC角色定义
`specrails://memory/{name}`	代理内存文件
`specrails://skills/{name}`	技能定义(`SKILL.md`)
`specrails://provider`	活动CLI提供程序信息（claude或codex）

中心资源（specrails中心）

阅读 ~/.specrails SQLite数据库：

URI	描述
`specrails://hub/projects`	所有已注册的带有元数据的项目
`specrails://hub/projects/{projectId}`	具有快速统计数据的单个项目详细信息
`specrails://hub/projects/{projectId}/jobs`	最近的作业（最近50个），包括状态、成本、持续时间
`specrails://hub/projects/{projectId}/jobs/{jobId}`	带有事件日志的完整作业详细信息
`specrails://hub/analytics`	全中心分析（过去30天）
`specrails://hub/projects/{projectId}/analytics`	具有每日成本时间表的项目特定分析

典型工作流程

hub_status → list_projects → enqueue_job → get_jobs → get_job_detail
   ↓              ↓              ↓             ↓              ↓
"Is it up?"  "What's there?"  "Launch it"  "How's it going?"  "What happened?"

检查系统健康状况

"Run the specrails doctor"        → doctor
"Is the hub running?"             → hub_status

发现和检查项目

"What projects do I have?"        → list_projects
"Show me details for DeckDex"     → get_project

运行和监视作业

"Implement ticket #42 on DeckDex"              → enqueue_job (command: "implement #42")
"Run a health-check on mechboards"             → enqueue_job (command: "health-check")
"Launch product-backlog on DeckDex with opus"   → enqueue_job (model: "claude-opus-4-6")
"What jobs are running right now?"              → get_jobs (status: "running")
"Show me the last 5 failed jobs"               → get_jobs (status: "failed", limit: 5)
"Why did job f496a1b0 fail?"                   → get_job_detail

跟踪成本和性能

"How much has DeckDex cost this week?"         → get_analytics (period: "7d")
"Show me analytics for all projects"           → get_analytics (no projectId)
"What's the success rate for specrails-core?"  → get_analytics
"Which project spent the most this month?"     → get_analytics (period: "30d")

建筑

┌─────────────────────┐     stdio      ┌──────────────────────────┐
│   MCP Client        │◄──────────────►│   specrails-mcp          │
│                     │                │                          │
│   Claude Code       │                │   Resources (read-only)  │
│   Claude Desktop    │                │   ├── openspec/          │
│   Cursor            │                │   ├── .claude/ (.codex/) │
│   Windsurf          │                │   └── ~/.specrails DBs   │
│   Codex CLI         │                │                          │
│   ...               │                │   Tools (read + action)  │
│                     │                │   ├── doctor             │
└─────────────────────┘                │   ├── hub queries        │
                                       │   └── enqueue_job → Hub  │
                                       └──────────────────────────┘

运输：stdio（通过stdin/stdout的JSON-RPC）
资源：只读。项目文件+中心SQLite数据库。
工具：读取查询总是安全的。 enqueue_job 通过集线器HTTP API创建作业。
供应商意识：自动检测Claude或Codex CLI，并从正确的配置目录读取。
没有文件系统写入：所有资源访问都是严格只读的，并防止路径遍历。

环境变量

变量	默认值	描述
`SPECRAILS_PROJECT_ROOT`	当前工作目录	specrails项目的根目录

集线器工具连接到 http://localhost:4200 （默认的specrails中心地址）。

先决条件

Node.js >= 20
特殊轨道芯 在项目中初始化(openspec/ 目录）
特殊轨道轮毂 在本地运行（仅适用于集线器工具： hub_status, enqueue_job等等）

发展

git clone https://github.com/fjpulidop/specrails-mcp.git
cd specrails-mcp
npm install
npm run build

命令	描述
`npm run dev`	使用tsx的观看模式
`npm test`	运行测试（Vitest）
`npm run test:coverage`	覆盖范围报告
`npm run lint`	埃斯林特
`npm run typecheck`	TypeScript检查
`npm run build`	生产建设

许可证

麻省理工学院

使用说明

mcp规范

快速开始

1.添加到您的MCP客户端

2.与您的AI助手交谈

工具

核心

Hub--查询

Hub--行动

enqueue_job 参数

已知命令

资源

项目资源（specrails核心）

中心资源（specrails中心）

典型工作流程

检查系统健康状况

发现和检查项目

运行和监视作业

跟踪成本和性能

建筑

环境变量

先决条件

发展

许可证

相关 MCP

小红书MCP服务

Figma MCP服务器

Markdown转换服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

`enqueue_job` 参数