SpecForge MCP 服务器（Model Context Protocol 实现）

使用说明（Markdown 格式）

• 项目简介 SpecForge MCP 服务器是一套基于 MCP（模型上下文协议）的后端服务，旨在为大型语言模型（LLM）客户端提供结构化的上下文信息和外部功能访问能力。它通过 JSON-RPC 接口暴露工具、资源、提示模板等核心能力，并实现会话管理、能力声明以及对外部插件的扩展接口。

• 主要功能点

  • MCP JSON-RPC 服务端：接收并处理 MCP 客户端发来的请求，返回标准化的 JSON-RPC 响应。
  • 工具注册与执行：提供工具清单及对工具的执行路由，支持创建快照、提交快照、导入流程等能力。
  • 资源、合同、变量等资源管理：提供对资源、合同、变量、导入任务等的创建、查询、更新、删除能力。
  • Prompts 与 UI 产出：提供对提示模板与 UI-roadmap 相关产出（如组件树、状态机、导出包）的生成与导出。
  • MCP 服务端自带鉴权：通过 Token 服务和简单的 Bearer Token 验证实现对 MCP 客户端的认证。
  • 会话与审计：提供导入会话、快照分析、审计日志等机制，支持追踪和复现。
  • 兼容性与扩展性：设计为可扩展的服务架构，易于接入 Cursor、Windsurf 等 Agent 类 IDE。

• 安装与运行步骤

  • 使用 Docker Compose（推荐，适合本仓库全栈部署）
    1. 复制并配置环境变量，确保 MCP_TOKEN、DATABASE_URL、JWT_SECRET 等必要参数可用。
    2. 执行 docker-compose up --build 启动全部组件（前端、后端、数据库等）。默认后端 MCP 服务器监听在 8081 端口。
  • 本地调试
    1. 先安装 Go 依赖并构建后端服务：在后端根目录执行 go mod download；再执行 go run ./backend/cmd/server/main.go。
    2. 设置环境变量 DATABASE_URL、MCP_TOKEN、JWT_SECRET 等后即可启动。后端默认监听 http://0.0.0.0:8080（HTTP API）与 MCP 服务端 http://0.0.0.0:8081。
    3. 访问 /health 可以快速检查服务可用性。
  • MCP 客户端连接配置
    • MCP 客户端需要知道 MCP 服务端的地址、启动命令及参数以建立连接。推荐使用标准的命令行或应用配置，示例配置如下（JSON，客户端仅作参考，实际未必需要直接执行代码）： { "server_name": "SpecForge MCP Server", "command": "docker-compose", "args": ["up", "--build"], "notes": "在生产环境中将容器化部署作为首选。确保 MCP_TOKEN、DATABASE_URL、JWT_SECRET 及服务端端口等与服务器配置匹配。" } 说明：该配置旨在描述客户端连接 MCP 服务器所需的最小信息，实际客户端使用时无需包含具体代码片段，只需知道服务器地址和认证信息即可建立连接。

• 服务器使用要点

  • MCP 请求类型：JSON-RPC 请求，常用方法包括 initialize、tools/list、tools/call、notifications/initialized 等。
  • 回复与错误处理：服务器返回标准 JSON-RPC 的 Result/Error 结构，提供清晰的错误码与信息。
  • 安全性与审计：服务端会对请求进行鉴权，错误处理与审计日志以便后续追踪。
  • 扩展性：工具与环境的定义、快照分析、导入流程等均分离成独立的处理分支，便于未来扩展新的工具或工作流。

• 基本使用方法（简要）

  • 客户端准备阶段：获取并配置 MCP 服务器地址、Token 等鉴权信息。
  • 连接并初始化：发送 initialize 请求以获取服务器能力与版本信息。
  • 列出可用工具：调用 tools/list 获取工具定义。
  • 调用具体工具：使用 call_tool 传入工具名称与参数，获取对应输出（如创建快照、分析结果等）。
  • 会话与导入：使用 Import 相关工具进行项目导入与快照提交，追踪状态与分析结果。
  • 结果渲染：将服务器返回的提示、分析结果等数据渲染到 LLM 的上下文中，以便进行下一步推理与生成。