内容
# 代理引导MCP
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
[](https://ko-fi.com/JunMystery)
<img src="docs/images/hero-banner.png" alt="代理引导MCP">
MCP服务器通过**168项技能目录**、捆绑引导语料库、工作流提示、限定项目代码上下文工具和**令牌优化引擎**提供AI代理引导，所有操作均通过**Stdio**传输。
技能来源于[Everything Claude Code (ECC) v2.0.0](https://github.com/affaan-m/ECC)和社区贡献，涵盖后端、前端、测试、安全、DevOps、数据、研究和12+语言生态系统。
---
## 安装
使用单个命令安装代理引导MCP服务器并配置所有本地IDE客户端：
**Linux / macOS（Bash）：**
```bash
curl -fsSL https://raw.githubusercontent.com/JunMystery/Agent-Guidance-MCP/main/scripts/install.sh | bash
```
**Windows（CMD / PowerShell）：**
```cmd
powershell -Command "irm https://raw.githubusercontent.com/JunMystery/Agent-Guidance-MCP/main/scripts/install.ps1 | iex"
```
*不需要事先安装Python — 脚本会自动引导`uv`（一个单二进制Python工具链）。*
### 验证安装
使用MCP检查器在本地测试：
```bash
DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector .venv/bin/python -m agent_guidance_mcp
```
然后调用`task_pipeline(...)`加载引导和限定项目上下文。有关工作流的详细信息，请参阅[使用指南](docs/usage.md)。
### 升级
**服务器 + IDE注册：** 重新运行上述安装命令。
**标准目录和技能：**
```bash
agent-guidance-mcp --update
```
**可执行包：**
```bash
uv tool update agent-guidance-mcp
```
### 预定自动更新
```bash
agent-guidance-mcp --auto-update # 每周（默认）
agent-guidance-mcp --auto-update monthly # 每月
```
或通过环境变量：`AGENT_AUTO_UPDATE_INTERVAL=weekly`
### 卸载
**Linux / macOS：**
```bash
curl -fsSL https://raw.githubusercontent.com/JunMystery/Agent-Guidance-MCP/main/scripts/install.sh | bash -s -- --uninstall
```
**Windows：**
```cmd
powershell -Command "irm https://raw.githubusercontent.com/JunMystery/Agent-Guidance-MCP/main/scripts/uninstall.ps1 | iex"
```
### 手动/开发者安装
```bash
python -m venv .venv
.venv/bin/pip install -e ".[dev]" # Linux / macOS
.venv\Scripts\pip install -e ".[dev]" # Windows
```
```bash
agent-guidance-mcp
.venv/bin/python -m agent_guidance_mcp # Linux / macOS
.venv\Scripts\python.exe -m agent_guidance_mcp # Windows
```
自定义语料库路径：
```bash
AGENT_GUIDANCE_ROOT=/path/to/Agent-Guidance
```
平台说明：[安装](docs/installation.md) · [客户端设置](docs/setup/client-configuration.md)
---
## 支持的IDE
与任何MCP兼容的客户端配合使用。安装程序自动配置：
| Claude Desktop / Claude Code | Cursor | VS Code (Copilot) |
| OpenCode / OMO | Gemini CLI | Windsurf |
| Cline / Roo-Code | Continue.dev | Antigravity |
---
## MCP界面
<img src="docs/images/tool-surface.png" alt="MCP工具界面" width="50%">
### 工具
| 工具 | 角色 | 关键操作 |
|---|---|---|
| `task_pipeline` | **调用第一个** — 一站式上下文准备 | 推荐 + 树 + 搜索 + UI + 执行序列 |
| `guidance` | 标准和技能目录 | `list`、`get`、`search`、`recommend`、`reason`、`docs`（Context7） |
| `project_context` | 限定项目文件操作 | `tree`、`search`、`read`、`symbols`、`references`、`structure`、`callers`、`callees`、`diff`、`snapshot` |
| `ui_ux` | 设计引导 | `search`、`design_system`、`slides` |
| `session_continuity` | 任务状态持久性 | `save`、`load`、`clear` |
| `health_check` / `diagnose` / `token_stats` | 操作 | 服务器状态、自我诊断、令牌节省 |
### 资源
| URI | 描述 |
|---|---|
| `standards://manifest` | 索引标准清单（JSON） |
| `standards://skill/{name}` | 按需技能胶囊（Markdown） |
| `standards://document/{identifier}` | 按slug查找标准文档（Markdown） |
| `standards://version` | 服务器版本信息（JSON） |
### 提示
`workflow_prompt(mode, subject, target)` — 按模式加载工作流：计划、测试、部署、调试等。
---
## 为什么使用代理引导MCP
AI编码代理快速消耗上下文。每次文件读取、每次grep、每次网络搜索都会消耗上下文窗口 — 当上下文窗口用完时，代理会忘记所有内容。代理引导MCP通过三个层次解决这个问题：
| 层次 | 功能 | 收益 |
|---|---|---|
| **上下文预算** | 限制文件读取为300行；智能截断源代码以保留结构 | 代理专注于相关代码，不会淹没在噪音中 |
| **引导目录** | 168项技能 + 编码标准 + 安全规则按需提供 | 代理遵循生产模式，无需提醒 |
| **令牌优化** | 在LLM到达之前剥离注释、折叠空白并重复利用输出 | **每个MCP响应减少40–80%的令牌** |
### 节省
在典型的500行React组件重构任务上测量：
<img src="docs/images/token-savings-chart.png" alt="令牌节省比较" width="65%">
```
无MCP 使用代理引导MCP
───────────── ──────────────────────
工具往返次数 12–18次 4–6次（task_pipeline合并）
使用上下文 ~45,000令牌 ~12,000令牌
文件读取 8+次完整读取 3次限定读取（每次300行）
标准查找 手动/猜测 通过guidance()自动查找
无效搜索 2–3次错误搜索 零（搜索-优先纪律）
首次修复时间 ~4分钟 ~45秒
```
### 令牌优化管道
每个MCP响应通过8阶段过滤器：
<img src="docs/images/token-pipeline.png" alt="令牌优化管道" width="40%">
```
原始响应
│
├─ 阶段1 ANSI剥离 ── 移除终端颜色代码
├─ 阶段2 正则表达式替换 ── 折叠噪音模式
├─ 阶段3 匹配/短路 ── 跳过空有效载荷
├─ 阶段4 行过滤 ── 仅保留相关输出行
├─ 阶段5 智能截断 ── 保留导入、签名、常量
├─ 阶段6 头/尾部保留 ── 前N行和后N行，带有省略标记
├─ 阶段7 最大行限制 ── 绝对上限
└─ 阶段8 空值保护 ── 如果所有内容都被过滤，则使用备用消息
│
▼
优化响应（小40–80%）
```
---
## 实际应用
### 场景： “在我的Express API中添加JWT身份验证”
**步骤1 — 代理调用`task_pipeline`（一次调用）**
```
Agent: task_pipeline(task="在Express API中添加JWT身份验证", focus="后端")
```
返回单个响应：
- **推荐**: 8项相关技能（api-design、security-review、backend-patterns、express-patterns...）
- **项目树**: Express项目目录结构
- **代码搜索**: 预先grep的结果，关键字为"auth"、"jwt"、"token"、"middleware"
- **执行序列**: 生命周期顺序排列的技能
**步骤2 — 代理咨询标准**
```
Agent: guidance(operation="search", query="JWT身份验证中间件Express")
```
返回：security-review技能、api-design模式、OWASP身份验证速查表 — 所有内容均预先加载，无需网络搜索往返。
**步骤3 — 代理仅读取所需内容**
```
Agent: project_context(operation="read", relative_path="src/middleware/auth.js")
```
返回：最多300行。如果文件有800行，`smart_truncate`会保留导入、函数签名和JSDoc — 跳过实现主体。
**步骤4 — 代理使用实时文档实施**
```
Agent: guidance(operation="docs", query="jsonwebtoken sign options", identifier="node-jsonwebtoken")
```
返回：Context7的当前`jsonwebtoken` API文档 — 无需臆造的API调用。
**结果**: 代理在~3次工具调用内编写生产级JWT中间件，而不是15+次调用，并具备自动安全审查意识。
---
## 环境变量
| 变量 | 目的 | 默认值 |
|---|---|---|
| `AGENT_GUIDANCE_ROOT` | 自定义标准语料库路径 | 捆绑语料库 |
| `AGENT_PROJECT_ROOT` | 重写项目根目录以使用上下文工具 | `.` （当前工作目录） |
| `AGENT_PROJECT_ALLOWED_ROOTS` | 安全的白名单目录 | 所有用户目录 |
| `AGENT_WATCHER_ENABLED` | 启用/禁用CodeGraph文件监视器 | `true` |
| `AGENT_WATCHER_INTERVAL` | 监视器轮询间隔（秒） | `30` |
| `AGENT_WATCHER_DEBOUNCE_MULTIPLIER` | 更改后的 debounce乘数 | `2.0` |
| `AGENT_WATCHER_REF_THRESHOLD` | 批量大小阈值 | `50` |
| `AGENT_AUTO_UPDATE_INTERVAL` | 自动更新计划 | `weekly` |
有关完整工具文档、响应格式和示例，请参阅[MCP界面](docs/reference/mcp-surface.md)。
---
## 文档
- [快速入门](docs/getting-started.md) — 首次使用指南。
- [安装](docs/installation.md) — 自动和手动设置。
- [使用指南](docs/usage.md) — 推荐的代理工作流和示例。
- [客户端设置](docs/setup/client-configuration.md) — VS Code、Copilot、Cursor、Gemini、OpenCode、Windsurf、Antigravity。
- [MCP界面](docs/reference/mcp-surface.md) — 所有工具、提示和资源。
- [项目上下文工具](docs/reference/project-context-tools.md) — 树、搜索、读取、快照、符号、引用。
- [技能概览](docs/skills/SKILLS_OVERVIEW.md) — 185+技能完整目录。
- [集成仓库](docs/integrations/integrated-repositories.md) — 代码库中的第三方仓库。
- [潜在集成](docs/integrations/potential-integrations.md) — 未来可能包含的候选集成。
- [开发指南](docs/development.md) — 测试、项目结构、维护者说明。
- [MCP集成指南](agent-guidance/mcp-integrations/README.md) — SQLite缓存、CodeGraph、Context7文档。
---
## 开发
```bash
python -m pytest
```
测试套件验证目录发现、MCP处理程序注册、标准搜索、推荐行为和项目上下文工具。更多详情请参见[开发指南](docs/development.md)。
