MCP AI Agent Guidelines

mcp-ai代理指南

](https://www.npmjs.com/package/mcp-ai-agent-guidelines)  ](https://nodejs.org) 

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

TypeScript ESM MCP服务器 暴露 20个公共教学工具 和 7实用工具，支持 102内部技能 涵盖18个领域家族——从需求发现和代码质量到治理、弹性和物理启发分析。

📖 ****

______________________________________________________________________

目录

• 需求
• 安装
• 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

# Interactive CLI
mcp-cli info

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

npm install mcp-ai-agent-guidelines

______________________________________________________________________

VS代码集成（一键）

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

  ](https://insiders.vscode.dev/redirect/mcp/install?name=ai-agent-guidelines&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22ghcr.io%2Fanselmoo%2Fmcp-ai-agent-guidelines%3Alatest%22%5D%7D) ](https://insiders.vscode.dev/redirect/mcp/install?name=ai-agent-guidelines&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22ghcr.io%2Fanselmoo%2Fmcp-ai-agent-guidelines%3Alatest%22%5D%7D&quality=insiders)

或者手动添加到用户设置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使用情况

包含一个交互式CLI向导，可在MCP主机外独立使用。这 已发布的包暴露了两个入口点：

• mcp-ai-agent-guidelines --用于编辑器和MCP主机的MCP stdio服务器入口点
• mcp-cli --用于入职、编排和诊断的交互式CLI

# Project onboarding
mcp-cli onboard init

# Re-open the orchestration editor
mcp-cli orchestration edit

# Quick re-entry for environment + model fleet only
mcp-cli orchestration edit --quick

# Direct skill invocation
mcp-cli --skill core-prompt-engineering --request "Write a system prompt for a coding assistant"

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

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

______________________________________________________________________

配置文件

• .mcp-ai-agent-guidelines/config/orchestration.toml --主编排权限（本地，不在git中跟踪）
• src/config/orchestration-defaults.ts --内置引导默认值用于在咨询模式下自动创建工作区配置 orchestration.toml 缺席

首次运行自动创建 orchestration.toml 来自内置的咨询默认值，包括语义角色占位符，以便在模型发现之前进行路由。跑 mcp-cli onboard init 自定义设置或 mcp-cli orchestration edit 重新打开交互式编辑器。

______________________________________________________________________

特性

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

______________________________________________________________________

公共MCP表面

ListTools 当前暴露 27工具 总计：

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

______________________________________________________________________

技能分类

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

物理技能(qm-*, gr-*)在调用之前需要明确的理由。路线穿过 physics-analysis 指令先行。

完整的分类详细信息： 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/ 是开发参考，而不是包运行时文件。

______________________________________________________________________

环境变量

技能门

技能执行由上述环境变量控制。物理技能(qm-*, gr-*)额外要求 ENABLE_PHYSICS_SKILLS=true 以及常规证据输入。模型可用性来源于 .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"
      }
    ]
  }
}

路线指引

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

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

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

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

______________________________________________________________________

贡献

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

______________________________________________________________________

许可证

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