stackguide-mcp

StackGuide MCP 服务

为 Cursor、VS Code 和其他 MCP 客户端中的 AI 编码助手提供动态上下文和主动工程工作流。

功能

@stackguide/mcp-server 帮助团队通过以下方式规范实现质量：

• 感知项目的规则／上下文加载
• 代码审查和健康度评分
• 自动检测配置并搭建技术栈脚手架
• 执行实际工作的主动 Agent 工作流（intake、plan、verify、release）
• 针对每个项目自适应的 TDD 偏好（模型 + 令牌配置）
• 根据严格的 MAIN DESCRIPTION 模板创建 Jira 工单
• 为交付流程编排跟踪器、VCS 和测试

此服务专为团队实际使用而构建，而不仅仅是提示词模板。

v4.x 新增内容

• 添加了主动 agent 工具（以执行为先的工作流）。
• init 现在会自动生成 .stackguide/config.json。
• 添加了对 GitHub、GitLab 和 Jira 的跟踪器服务支持。
• 添加了 VCS 服务，支持分支检查、提交解析、CI 状态以及 PR/MR 创建。
• 添加了测试运行器服务，支持结构化执行 test／lint／build。
• 更新了 TDD 提示词，改为使用主动工具调用，而不是大型被动 Markdown 内容。
• 强化了本地持久化：
  • .stackguide 产物不再纳入版本控制
  • 仓库防护机制会阻止意外跟踪本地产物
  • 缓存和健康历史记录包含完整性验证与更安全的写入

按 IDE 安装

Cursor

• 文件（工作区）：.cursor/mcp.json
• 文件（全局）：~/.cursor/mcp.json

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

JetBrains（IntelliJ、WebStorm、PhpStorm 等）

• 打开 Settings | Tools | AI Assistant | Model Context Protocol (MCP)。
• 点击 Add 并粘贴 JSON 配置。
• 建议将其设为 Project-level，除非你希望使用全局范围。

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

VS Code

• 要求：启用 MCP 的 GitHub Copilot Chat。
• 文件（工作区）：.vscode/mcp.json
• VS Code MCP 架构使用 servers 作为根键。

{
  "servers": {
    "stackguide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

Visual Studio（Windows，2022 17.14+ / 2026+）

• 启用 GitHub Copilot Agent 模式。
• 支持的配置位置包括：
  • %USERPROFILE%\\.mcp.json（全局）
  • <solution>\\.mcp.json（仓库范围）
  • <solution>\\.vs\\mcp.json（解决方案／用户范围）
• Visual Studio MCP 架构使用 servers 作为根键。

{
  "servers": {
    "stackguide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

使用方法（任何 IDE）

1. 添加 MCP 配置后，重启 IDE。
2. 在 Agent／工具模式下打开 AI 聊天。
3. 调用 setup 检测项目上下文。
4. 调用 init action:"full" 搭建 .stackguide/ 和默认配置。
5. 使用 agent 操作（intake、create_ticket、plan、verify、release）执行交付流程。

快速开始

1. 配置项目：

setup type:"react-typescript" enableAdaptiveTdd:true model:"gpt-5" integrations:["jira","github"] tokenMode:"compact"
init action:"full" model:"gpt-5" tokenMode:"compact" integrations:["jira","github"] mcpSyncTargets:["cursor","root"] applyMcpTemplates:true

1. 检查生成的配置：

init action:"status"
agent action:"status"

1. 运行主动 TDD 工作流：

agent action:"intake" ticket:"PROJ-123"
agent action:"create_ticket" mainDescription:"<MAIN DESCRIPTION>" projectKey:"PROJ"
agent action:"plan" brief:"<brief-from-intake>"
agent action:"verify"
agent action:"release" version:"v1.2.0"

工具（16 个）

核心

• setup：为项目类型配置 StackGuide 上下文
• context：显示当前已加载的上下文
• rules：列出／搜索／获取／选择规则集
• knowledge：列出／搜索／获取知识文件
• review：分析文件／URL／项目代码质量

实用工具

• cursor：浏览／导入社区规则
• docs：获取／搜索／列出文档
• config：保存／加载／导出／导入配置
• custom_rule：创建／更新／删除／列出项目自定义规则
• help：按主题提供使用帮助

高级

• generate：生成样板代码（组件／钩子／服务／测试／API／模型／工具）
• health：项目健康度评分和建议
• analyze：项目智能分析（结构／配置／依赖／生成／应用）

工作流

• workflow：延迟加载原始工作流资源（Agent/技能/钩子/命令）
• init：使用适配技术栈的默认值搭建 .stackguide
• agent：主动工作流执行器（status、intake、create_ticket、plan、verify、release）

主动工作流详情

agent action:"intake"

• 从已配置的跟踪工具读取工单
• 返回标准化概要和待补充信息
• 提议分支命名规范
• 可选先创建 Jira 工单（createFromDescription:true）

agent action:"create_ticket"

• 使用严格的 MAIN DESCRIPTION 格式创建 Jira 问题
• 使用 .stackguide/config.json 中的项目默认值（projectKey、issueType）
• 如果未提供 summary，则从 MAIN DESCRIPTION 的第一行提取

agent action:"plan"

• 检查约定和项目结构
• 制定垂直切片计划
• 以结构化格式准确返回 3 个目标测试

agent action:"verify"

• 按层执行已配置的测试、lint 和构建
• 检查分支命名、提交约定和 TDD 测试预算
• 返回阻塞项列表和最终通过/失败报告

agent action:"release"

• 检查 CI 状态
• 解析自上一个标签以来的提交
• 建议 semver 影响程度（major / minor / patch）
• 可创建标签和 PR/MR（启用时）

本地数据与安全

init 会生成：

• .stackguide/config.json（项目工作流配置）

运行时/本地产物：

• .stackguide/analysis-cache.json
• .stackguide/health-history.json

这些文件仅存在于本机，不得提交。

仓库防护

pnpm lint 包含：

pnpm run guard:repo

如果 .stackguide 产物被纳入版本控制，防护检查将失败。

完整性强化

缓存/历史记录持久化包含：

• 边界/符号链接检查
• 文件大小和条目数限制
• 原子写入策略
• 校验和验证
• 可选的 HMAC 签名，使用：

STACKGUIDE_INTEGRITY_KEY=<long-random-secret>

对于团队，可在本地/开发和 CI 环境中配置 STACKGUIDE_INTEGRITY_KEY，以增强防篡改能力。

支持的技术栈

python-django、python-fastapi、python-flask、react-node、react-typescript、vue-node、nextjs、express、nestjs、laravel、rails、golang、rust、custom。

开发

所有命令均使用 pnpm。

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm dev

发布与版本策略

• 当前安全基线：4.1.2+
• 由于本地产物管理问题，npm 上 3.0.0 至 4.1.1 版本已弃用。
• 所有环境均使用最新的 4.x 版本。

注册表标识符

• npm 包：@stackguide/mcp-server
• MCP 注册表服务：io.github.isucorp-taimiralain/stackguide-mcp

许可证

GPL-3.0