stackguide-mcp

StackGuide MCP Server

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

功能

@stackguide/mcp-server 通过以下功能帮助团队统一实施质量：

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

此服务面向团队的实际使用，而不只是提示词模板。

v4.x 新增内容

完整历史记录：CHANGELOG.md。

• v4.3.1 - 更新通知器：StackGuide 每天在后台检查一次 npm，并在有新版本时于每个会话中通知一次，同时提供安全的更新命令。使用 STACKGUIDE_NO_UPDATE_CHECK=1 禁用。
• v4.3.0 - 团队模式：
  • setup wizard:true 会询问技术栈、架构、方法论、约定和跟踪工具，然后在仓库根目录写入共享的 stackguide.config.json。提交此文件，以便每位队友获得相同的上下文。
  • 启动时，StackGuide 会查找该文件（包括子文件夹中的文件）并加载它，而不会运行 setup 或重新检测项目。context 会为每种架构和方法论返回一条指导信息。
  • 可选的 ruleCategories 可限制加载的规则（节省 token）。文件中现有的 healthWeights 会保留。
  • 多 Agent 角色会遵循你正在使用的 IDE（从 MCP 客户端检测）。默认值：Claude Code 为 opus / haiku / haiku；Cursor 为 inherit（你选定的模型，例如 Composer 或 Grok）/ fast / fast；其他 IDE 为 inherit。向导会询问每个角色应使用哪个模型（推荐默认值、你最常用的模型优先，或输入 IDE 列出的任意 ID）；输入 models:{planner,implementer,verifier} 或 models:{} 以接受默认值。选择会按 IDE 保存到 stackguide.config.json，因此混合使用不同 IDE 的团队不会互相冲突。
  • agent action:"plan" 会返回适用于当前 IDE 的 delegation 块，向导还会将 stackguide-implementer.md / stackguide-verifier.md 写入 .claude/agents/ 和 .cursor/agents/。已编辑的文件会保留；仅刷新其中的 model: 行。
  • 重新运行 setup wizard:true 会编辑已保存的配置；.stackguide/ 保持本地状态并受保护。
• 新增主动式 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）完成交付流程。

快速入门

团队设置（每个项目设置一次，然后提交 stackguide.config.json）：

setup wizard:true
setup wizard:true type:"nextjs" architecture:"clean" methodology:"tdd" conventions:["Use named exports"] tracker:"jira"

个人设置：

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"

• 按层执行已配置的测试/代码检查/构建
• 检查分支命名、提交规范和 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+
• 由于本地构件清理问题，3.0.0 至 4.1.1 版本已在 npm 中弃用。
• 在所有环境中使用最新的 4.x 版本。

注册表标识符

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

许可证

GPL-3.0