agentkit

AgentKit — 一个受治理的 MCP 工具服务

一个 MCP 服务，其中工具采用声明式定义、效果经过类型化处理，且每项操作都受策略管控并经过审计。它适用于任何 MCP 客户端（Claude Desktop、Cursor、LangGraph、Claude Agent SDK、CrewAI）。

在线应用： agentkit.ysiddo-ai-projects.app。

• 研究背景： RESEARCH.md / 在线研究文档
• 实证基准测试： BENCHMARK.md / 在线基准测试仪表板
• 用户指南： 在线用户指南
• 自托管指南： SELF_HOSTING.md

它与典型 MCP 服务有三点不同：

• 声明式工具。 使用 YAML 为你自己的 Postgres 或 HTTP API 定义工具，无需 Python，也无需分叉项目。（docs/REUSE.md）
• 类型化效果。 每个工具都声明一种效果（read、write 或 destructive），且会实际修改数据的工具确实会修改数据。
• 不依赖提示词的防护措施。 默认禁用写入；破坏性操作需要由人保管、模型永远看不到的审批令牌；每个修改数据的工具都支持 dry-run；每次调用（无论允许还是拒绝）都会经过审计。 （SECURITY.md）

下方附带的商业智能工具是参考工具包。它们展示了端到端的工作机制，但并不代表该服务所能提供工具的上限。

功能介绍

参考 BI 套件（内置）：

• 6 个核心 MCP 工具：query_kpis、get_company_health、detect_kpi_anomalies、forecast_metric、list_available_metrics、get_executive_summary——此外还包括从声明式 YAML 套件（packs/）加载的任意工具，因此运行时实际工具数量为 6 个或更多，而非固定数量。随附的 annotations 套件会额外添加 3 个工具（list_annotations、annotate_metric、retract_annotation），用于演示受保护的写入／破坏性操作路径——详见下文。
• 10 个 MCP 资源：kpi://{domain}/latest，分别对应本项目实际预置数据中的领域：Finance、People、Operations、Customer、Engineering、Growth、Logistics、ESG、IT、Security（src/agentkit_mcp/data/seed.py）。
• 1 个可复用提示词：monthly_executive_briefing

领域列表、工具套件集合以及资源／提示词注册信息，均源自此服务提供的同一份数据（src/agentkit_mcp/data/seed.py、packs/*.yaml），而非硬编码，因此添加领域或工具套件会自动扩展此列表。你也可以添加自己的 @mcp.resource／@mcp.prompt 装饰器。参见 docs/REUSE.md。

写入和破坏性操作。 annotations 套件允许 Agent 为某项指标记录持久备注（annotate_metric，effect write），并软删除错误备注（retract_annotation，effect destructive；该操作需要由人工持有、模型永远无法看到的 AGENTKIT_APPROVAL_TOKEN）。两项功能默认均关闭（AGENTKIT_ALLOW_WRITES=false）。参见 SECURITY.md 和 RESEARCH.md 第 2 节，了解策略引擎模型。

平台功能：

• 声明式工具套件——通过 YAML 为你自己的 Postgres／HTTP 添加工具（packs/）
• 类型化操作效果 + 策略引擎——GET /api/policy 发布能力范围
• 审计跟踪——GET /api/audit，记录允许和拒绝的操作及拒绝原因
• 多提供商大模型路由，支持自托管——GET /api/llm-routing
• workflow.py 中的 LangGraph 3 Agent 工作流（Planner → Analyst → Reporter）
• demos/claude_agent_sdk_demo.py 中的 Claude Agent SDK 演示
• demos/crewai_demo.py 中的 CrewAI 演示
• research/dspy_experiment.py 中的 DSPy 研究框架
• 90 多项测试，涵盖冒烟测试、API、集成、MCP 协议、策略防护措施和 LangGraph 工作流

PyPI 包

pip install agentkit-mcp
agentkit-mcp               # starts the server (stdio for MCP clients; set PORT for SSE)

对于 MCP 客户端，uvx 可以运行已发布的软件包，无需检出代码：

{ "mcpServers": { "agentkit": { "command": "uvx", "args": ["agentkit-mcp"] } } }

快速开始

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt      # server only; demos and research scripts: requirements-demos.txt
cp .env.example .env  # fill in keys + POSTGRES_URL
python mcp_server.py

Claude Desktop 配置

添加到 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "agentkit": {
      "command": "python",
      "args": ["/abs/path/to/agentkit/mcp_server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "POSTGRES_URL": "postgresql://...",
        "LOG_LEVEL": "DEBUG",
        "TELEMETRY_OPT_OUT": "true"
      }
    }
  }
}

这里必须设置 MCP_TRANSPORT=stdio——否则 mcp_server.py 默认会通过 SSE（网络端口）提供服务，而不是通过 Claude Desktop 启动它时使用的管道进行 JSON-RPC 通信，因此不会显示任何工具。本地 stdio 模式无需设置 MCP_AUTH_TOKEN（操作系统进程边界就是身份验证边界）；该变量仅在 SSE／网络路径下才有用。

多提供商大模型路由

3 个 Agent 的 LangGraph 工作流（workflow.py）以及演示和研究脚本通过 LiteLLM 将各个角色路由到各自的模型，使用纯 provider/model 字符串进行配置，无需更改代码即可切换提供商：

• LLM_REASONING — 规划器和报告 Agent（默认使用 anthropic/claude-sonnet-4-6）
• LLM_DEFAULT — 调用工具的分析 Agent（默认使用 groq/openai/gpt-oss-120b）
• LLM_JUDGE — 供评估套件使用（默认使用 anthropic/claude-haiku-4-5）
• LLM_LOCAL + INFERENCE_MODE=local — 路由到本地/可自托管模型（例如 Ollama），而非托管式提供商

为上面引用的模型设置相应的提供商 API 密钥（GROQ_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY）。参见 .env.example。

• 诊断：将 LOG_LEVEL 调整为 DEBUG 以启用详细日志。
• 遥测：默认情况下，MCP 控制台命令和 REST 外观都会发送一次匿名启动信号（服务名称、版本、随机安装 ID；不包含提示词、工具调用或应用数据）。TELEMETRY_URL 可将其重定向到你自己的收集器；设置 TELEMETRY_OPT_OUT=true 或 DO_NOT_TRACK=1 可将其禁用。上面的 Claude Desktop 代码片段设置了 TELEMETRY_OPT_OUT。

重启 Claude Desktop，然后询问：

• “我们公司目前的健康状况如何？”
• “预测未来 6 个月的收入。”
• “Finance KPI 中是否存在异常？”

LangGraph 工作流

from agentkit_mcp.workflow import analyze
result = analyze("What drove gross margin in Q1?")
print(result["report"])

架构

调用漏斗、策略模型、工具包和设计决策详见 ARCHITECTURE.md，仪表板中还提供交互式版本。REST 外观（/api/...）通过 HTTP 向仪表板和常规调用方提供相同的工具、策略、审计和路由视图。每个配置变量均在 .env.example 中说明。

        Claude Desktop / Cursor / LangGraph
                      │
                      ▼ MCP
              ┌────────────────────────┐
              │     mcp_server.py      │
              │  6 core tools (read)   │
              │  + N pack tools        │
              │    (read/write/        │
              │     destructive)       │
              │ 10 resources, 1 prompt │
              └────────────┬───────────┘
                            │
        ┌───────────────────┼──────────────────┐
        ▼                   ▼                  ▼
   pg_store            insights          forecasting
   (KPIs, real         (health,          (scikit-learn
   domains + write-    anomalies)        LinearRegression
   back annotations)                     + Monte Carlo CI)

设计说明

• 一个服务，两种传输方式。 同一组工具通过 stdio（本地客户端）和 SSE（网络）提供。
• 能力策略引擎。 效果分为读取、写入和破坏性操作，并在模型下层强制执行，不受提示词影响。
• 客户端覆盖。 已通过 Claude Desktop、Cursor 和 Devin 配置进行测试（参见下方的集成指南）。

完整的形式化说明、文献背景和引用详情，请参见 RESEARCH.md。

基准测试复现套件

运行可复现的基准评估套件：

# Test MCP framework overhead
python3 eval/run_benchmarks.py --seed 42

# Full 43-scenario LangGraph suite across all 10 KPI domains
python3 eval/run_dspy_eval.py

# Comprehensive MCP tool execution metrics
python3 eval/run_mcp_tools_benchmark.py

集成指南（Claude Desktop、Cursor、Devin）

• Claude Desktop：参见 claude_desktop_config.example.json 和 docs/INTEGRATION_GUIDE.md
• Cursor IDE：参见 cursor_mcp.example.json
• Devin AI Agent：参见 devin_mcp.example.json

自动化客户端验证：

python3 tests/test_mcp_client.py

支持项目

如果 AgentKit 对你有帮助，为仓库点个星有助于其他工程师发现它；关注 @Yacine-ai-tech 是了解新版本最简单的方式。将链接分享给遇到同样问题的同事，我们也非常欢迎。

问题和实践记录请发布到 Discussions；可复现的错误请提交到 Issues。

许可证与企业使用（双重许可）

本项目根据 AGPL-3.0 License 开源。研究人员、学生和开源爱好者均可免费使用。 商业许可证：参见 COMMERCIAL.md。