AI代理指令工具集

mcp-ai代理指南

[！小心] 实验/早期阶段： 这 研究演示器 该项目引用了快速发展的第三方模型、工具、定价和文档。将输出视为建议，并在生产使用前根据官方文档和您自己的基准进行验证。

TypeScript ESM MCP服务器 暴露 19种公共教学工具 和 3个实用工具，支持 72内部技能 涵盖16个领域家族——从需求发现和代码质量到治理和弹性。

📖 GitHub Pages上的完整文档

目录

• 需求
• 安装
• VS代码集成（一键）
• MCP服务器配置
• CLI使用情况
• 特性
• 指令工作流
• 技能分类
• 配置
• 发展
• 环境变量
• 贡献
• 许可证

需求

安装

npx（零安装，建议用于MCP配置）

npx -y mcp-ai-agent-guidelines@latest

全局安装

npm install -g mcp-ai-agent-guidelines

# MCP stdio server entrypoint
mcp-ai-agent-guidelines

# IDE hook + skill-file installer
mcp-cli --help

本地安装（单仓库/项目依赖）

npm install mcp-ai-agent-guidelines

VS代码集成（一键）

单击下面的徽章，将此MCP服务器直接添加到VS代码（用户设置→ mcp.servers):

或者手动添加到用户设置JSON：

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "npx",
        "args": ["-y", "mcp-ai-agent-guidelines@latest"]
      }
    }
  }
}

使用Docker：

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"]
      }
    }
  }
}

MCP服务器配置

将服务器添加到MCP主机配置中。入口点是 dist/index.js 并通过以下方式进行通信 stdin/stdout.

克劳德桌面(~/Library/Application Support/Claude/claude_desktop_config.json)

[！重要] Claude Desktop生成的服务器的工作目录与您的项目不同。 集 MCP_WORKSPACE_ROOT 到您希望服务器写入状态的项目的绝对路径。

{
  "mcpServers": {
    "ai-agent-guidelines": {
      "command": "npx",
      "args": ["-y", "mcp-ai-agent-guidelines@latest"],
      "env": {
        "MCP_WORKSPACE_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

VS代码(.vscode/mcp.json 或用户设置）

{
  "servers": {
    "ai-agent-guidelines": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ai-agent-guidelines@latest"],
      "env": {
        "MCP_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

从本地构建

{
  "mcpServers": {
    "ai-agent-guidelines": {
      "command": "node",
      "args": ["/path/to/repo/dist/index.js"]
    }
  }
}

CLI使用情况

已发布的包公开了两个入口点：

• mcp-ai-agent-guidelines --用于编辑器和MCP主机的MCP stdio服务器入口点（主界面；代理通过此界面实现所有功能）
• mcp-cli --一个精简的IDE集成安装程序。它不会复制MCP服务器功能；它的唯一目的是连接钩子脚本和每个IDE SKILL.md 代理本身无法安装的文件。

# Install SessionStart / PreToolUse hooks for an IDE
mcp-cli hooks setup --client vscode        # or copilot-cli / claude-code
mcp-cli hooks print --client claude-code   # preview without writing

# Emit per-IDE skill files for every public instruction
mcp-cli onboard skills --target all        # copilot + claude + codex
mcp-cli onboard skills --target claude --global   # user-home install

指令工具输入模式——公共指令工作流共享此形状：

{
  request: string;        // required — the task description
  context?: string;       // optional — background context
  options?: object;       // optional — skill-specific overrides
}

配置文件

• .mcp-ai-agent-guidelines/config/orchestration.toml --可选编排覆盖。MCP服务器 不再自动写入 这个文件；违约来自 src/config/orchestration-defaults.ts 在记忆中。显式写入文件（通过 mcp-cli 不再可用--手动编辑，或通过 model-discover MCP工具的保存操作），如果您需要覆盖建议默认值。
• src/config/orchestration-defaults.ts --当工作区配置缺失时，内存中会使用内置默认值。

特性

• 19种公共教学工具 通过MCP指令面暴露
• 3个公用工具 用于工作空间、模型发现和可视化操作（在任何操作之前 HIDDEN_TOOLS 过滤）
• 72内部技能 跨16个域前缀--请参阅 技能分类
• 仿生自适应路由：ACO，Hebbian，黏菌，群体，稳态，克隆突变，重播
• 治理层：快速注射硬化、PII护栏、政策验证、规范的工作流程设计
• 模型编排指南：5种多模型模式（平行评论、草案审查、多数票、级联、自由三重）
• 零运行时LLM调用 --咨询产出；连接一个具体的执行器，以实现真正的LLM调度
• xstate v5 内置状态机编排
• 笔迹学 拓扑技能排序的图路由

公共MCP表面

ListTools 暴露 22工具 在整个表面上(MCP_FULL_SURFACE=true)；默认的细长曲面仅显示 task-bootstrap 和 meta-routing:

72个技能定义是内部工作流资产，而不是单独作为MCP工具公开。看 文档 以获取完整的工具参考。

技能分类

技能按照18个特定领域的前缀进行组织：

完整的分类详细信息： docs/architecture/03-skill-graph.md.

指令工作流

20个任务驱动的教学工作流程将内部技能编排成完整的任务流：

建筑

看 docs/architecture/ 用于ADR和全模块布局。入口点是 src/index.ts；指令实时生效 src/instructions/，技能 src/skills/，并在中生成了工具定义 src/generated/ （不要手工编辑）。

发展

# Install dependencies
npm install

# Type-check
npm run type-check

# Build (tsc → dist/)
npm run build

# Watch mode
npm run dev

# Run MCP server
node dist/index.js

代码质量

npm run check          # biome check (lint + format)
npm run check:fix      # auto-fix
npm run quality        # full suite: verify_matrix + type-check + workflow-docs + biome

编辑规范注册表或工作流规范后重新生成生成的工具定义

python3 scripts/generate-tool-definitions.py
npm run build

验证技能/指导覆盖矩阵（需要零孤儿）

python3 scripts/verify_matrix.py

测试

npm test                  # vitest run
npm run test:coverage     # vitest + v8 coverage (80% threshold)

测试与源代码位于同一地点(src/**/*.test.ts)和in src/tests/.

已发布的包说明：npm包附带 dist/, README.md，以及 LICENSE.仅存储库源资产，如 docs/, .github/，以及 scripts/ 是开发参考，而不是包运行时文件。

环境变量

目标导向的输出和纤薄的表面。 形势发生了转变 将工具的关键字匹配模板应用于项目特定的可交付成果中 20个公共工具中的19个 --域工具(code-review, issue-debug, feature-implement，…）加上两种薄型表面工具(meta-routing → 路由决策， task-bootstrap → 定向简报）。 analogy-think 是唯一的直通（它已经进入特定请求 隐喻）。隐藏域工具仍然可以按名称调用；集 MCP_FULL_SURFACE=true 列出它们以供发现。

| MCP_SERENA_COMMAND |unset |选择加入。设置后，服务器通过stdio将Serena生成为子MCP服务器，并直接解析Serena查询。未设置（默认）时，服务器会发出结构化 公告 主机模型通过其自己的Serena连接执行——当主机（例如Claude Code）已经运行Serena时建议使用。 | | MCP_SERENA_ARGS |unset |传递给的空格分隔参数 MCP_SERENA_COMMAND示例： --from git+https://github.com/oraios/serena serena-mcp-server. | | MCP_SERENA_CWD |unset |生成的Serena孩子的工作目录。默认为父进程cwd。 |

符号和内存后端（Serena）

Serena的LSP支持的符号表面和每个项目的记忆可以丰富工具响应。两种模式：

• 咨询模式（默认） --没有设置。工具响应附加 🧭 Serena enrichment available 页脚，精确命名Serena工具(mcp__serena__find_symbol, mcp__serena__list_memories等等）和主机模型应该调用的参数。当您的MCP主机已经将Serena作为兄弟服务器加载时（例如配置了Serena的Claude Code），请使用此选项。
• 孩子出生模式（选择加入） --set MCP_SERENA_COMMAND=uvx 和 MCP_SERENA_ARGS="--from git+https://github.com/oraios/serena serena start-mcp-server --project <your-project-path>"服务器在启动时生成Serena一次，并直接解析查询，将数据嵌入响应页脚。针 --project 明确地说，因为Serena的全球注册表不会自动激活新的 cwd。当没有主机级别的Serena可用时，使用此模式。用以下工具验证接线 npm run test:mcp:serena （要求 MCP_SERENA_E2E=1 和 uvx 安装）。

两种模式都通过相同的内部接缝(src/serena/client.ts)，因此无论模式如何，工具代码路径都是相同的。

技能门

技能执行由上述环境变量控制。模型可用性来源于 .mcp-ai-agent-guidelines/config/orchestration.toml; strict_mode = false 仅允许警告， strict_mode = true 缺失模型上的块。

自动模式和会话挂钩

长时间运行的代理会话（VS Code Copilot、Claude Code、Copilot CLI）在最初的几次交换后可能会偏离MCP工具。这 会话挂钩 该机制通过在IDE生命周期边界注入轻量级提醒来抵消这一点。

钩子的作用是什么

快速安装

# VS Code / Copilot CLI (writes to ~/.copilot/hooks/)
mcp-cli hooks setup --client vscode

# Claude Code (writes to ~/.claude/)
mcp-cli hooks setup --client claude-code

# Inspect what will be written without touching the filesystem
mcp-cli hooks print --client vscode

手动安装

将以下JSON复制到 ~/.copilot/hooks/mcp-ai-agent-guidelines-hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "mcp-ai-agent-guidelines hooks remind-session"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "mcp-ai-agent-guidelines hooks remind-drift"
      }
    ]
  }
}

手动安装：添加 scripts/hooks/session-start-bootstrap.mjs 作为SessionStart挂钩 ~/.claude/settings.json （或 ~/.copilot/hooks/).

路线指引

这 .claude/rules/ 目录包含IDE可读路由表：

• .claude/rules/default.md --普遍症状→ 刀具流水线表与反模式
• .claude/rules/copilot.md --VS Code Copilot特定快速参考和会话开始清单

这些文件由Claude Code、Copilot的自定义指令系统和Serena的钩子集成层自动拾取。

[！注意] 已发布的npm包 不 包括 .claude/rules/。如果你从npm安装并想要这些路由规则，请将它们从GitHub存储库复制到你的工作区。

贡献

欢迎投稿！看 贡献.md 了解指导方针、代码标准和技能/指令开发工作流程。

许可证

麻省理工学院 ©2025安塞尔莫