mcp-agent-toolkit

在线演示： 尚未部署——计划部署于 agent.build-with-deepak.com。 本仓库已完成并通过本地验证（构建、lint、25 个单元测试——包括一次真实的 MCP 协议往返——以及 5 个端到端测试）；但尚未部署，也未针对实时 Ollama/Postgres 环境进行过验证。参见状态。

问题所在

大多数“AI 智能体”演示不过是将一次隐藏的工具调用包装成自主行为。本项目则展示了其完整过程：一个 Model Context Protocol 智能体，配备三个真实工具——一个只读的 PostgreSQL 商业数据库、一个实时天气 API 和一个计算器——回答那些确实需要多个工具配合的问题（“来自迪拜客户的总收入，以及那里的天气如何？”）。每次工具调用、其参数、结果、延迟，以及——重要的是——其失败以及模型从失败中的恢复过程，都会实时流式呈现在屏幕上。

Related MCP server: MCP Tool Server

试用

使用演示账户继续会针对真实 API 发起一个真实的 2 小时会话——相同的智能体、相同的工具、相同的数据。示例数据库是共享且只读的，因此演示会话无需按用户进行清理：访问者所做的任何操作都无法写入任何数据。注册（持久化按用户数据）正在进行中；注册按钮和 POST /api/auth/register（501）都如实说明了这一点。

架构

flowchart TB
    subgraph Browser
        UI[Angular SPA<br/>login → live tool-call timeline]
    end

    subgraph VPS -- host nginx, TLS
        Nginx[nginx :443]
    end

    subgraph "Docker Compose stack"
        Web[web container]
        subgraph API [api container — NestJS]
            Loop[Agent loop]
            Client[MCP Client]
            Server[MCP Server]
        end
        PG[(PostgreSQL<br/>sample dataset<br/>mcp_readonly role)]
    end

    Ollama[Ollama llama3.1 — on the VPS]
    Meteo[Open-Meteo API]

    UI -->|HTTPS| Nginx --> Web -->|/api/*| Loop
    Loop -->|chat + tools| Ollama
    Loop -->|listTools / callTool| Client
    Client <-->|MCP protocol, in-memory transport| Server
    Server -->|query_database| PG
    Server -->|get_weather| Meteo
    Server -->|calculate| Server

循环过程：模型接收问题以及 MCP 发现的工具模式 → 发出工具调用 → 每次调用都通过 MCP 客户端执行 → 结果（包括错误）返回给模型 → 重复直到模型以文字形式回答或达到步骤上限（默认 6）。每一步都是一个 SSE 事件。

关键决策与权衡

一个进程内同时包含真实的 MCP 服务器和客户端。 这些工具本可以是普通函数——但协议边界才是关键。智能体循环只与 MCP 客户端通信：它通过 listTools() 发现工具，并通过 callTool() 调用它们，与通过 stdio 或 HTTP 与外部服务器通信的方式完全相同。将工具移出此进程只需更改一行传输代码，而无需改动智能体本身。内存传输使单 VPS 演示无需额外端口和子进程监管，同时 SDK 仍双向验证模式——单元测试套件实际执行的是真实握手，而非模拟。

SQL 注入被视为默认状态，而非边缘情况。 智能体根据陌生人的自然语言问题编写 SQL——这本质上就是不可信输入。两层防护：应用端守卫（sql-guard.ts：注释剥离、单语句、仅 SELECT/WITH、一个能识别 set_config 不是 set 的关键词黑名单，以及一个将结果限制在 100 行内的子查询包装）快速失败并返回模型可处理的错误消息；在其之下，查询以专用 mcp_readonly Postgres 角色执行——仅授予 SELECT 权限、default_transaction_read_only=on、5 秒语句超时——即使守卫存在缺陷，这一层仍然有效。守卫自身的测试记录其接受的词法限制。

工具错误会反馈给模型，而非作为失败呈现。 失败的工具调用以 isError 结果返回，并作为工具输出进入对话。模型读取错误、修正 SQL 或选择其他城市并重试——UI 会精确标注这一过程（“错误返回给模型——观察下一步”）。观察恢复过程比从不失败更能证明工程能力。

计算器是一个 60 行的解析器，而非 eval。 将 LLM 编写的表达式交给任何 JavaScript 求值器都会把计算器变成代码执行工具。递归下降加显式语法是无聊但正确的替代方案；其测试包括 1 + 1; process.exit()。

循环步骤非流式；时间线才是流。 模型响应是工具调用还是最终答案只有在完整时才能确定，而工具调用响应通常较短。真正流式输出的是实际有趣的部分——工具调用及其结果实时呈现。最终散文答案作为一个事件到达。（与兄弟路由演示相同的 SSE-over-POST 传输决策，原因相同。）

天气使用 Open-Meteo。 免费且无需密钥：无人值守的公共演示若包含第三方 API 密钥，既可能泄露密钥，也可能产生账单。权衡——无 SLA——是可以接受的，因为天气工具故障本身就是错误处理路径的实时演示。

固定样本数据集，固定 ID。 种子数据使用 ON CONFLICT DO NOTHING，因此每次启动都会收敛到相同的 15 个客户 / 12 个产品 / 32 个订单，而非累积重复数据。城市选择使得数据库 + 天气问题能自然组合（迪拜、新德里、伦敦……）。

数据库设置与重置

模式、样本数据和 mcp_readonly 角色的授权位于 apps/api/db/schema.sql 中，每次 API 启动时以幂等方式应用；角色本身（密码来自 MCP_READONLY_PASSWORD）在 db.service.ts 中创建，因为 CREATE ROLE 无法接受参数化密码。pnpm db:reset 删除样本表；下次启动时重新创建所有内容。这里没有常规的演示数据清理——这是设计使然：访问者无法写入。

在 100 倍规模下我会做的改变

内存 MCP 传输是第一个需要替换的部分：真正的多租户工具服务器应作为独立服务运行（stdio 子进程或 HTTP），在协议边界进行按工具授权和审计日志记录——本代码库已为此做好了准备。智能体循环将增加持久化对话（一个以会话为键的 conversations 表——注册账户的第一个自然功能）、在调用独立时并行执行工具，以及在步骤上限之外增加 token 预算上限。SQL 工具将完全停止暴露原始 SELECT：在规模下，发布命名、参数化的查询模板，让模型填充参数——这里的守卫加只读角色模式是演示规模的版本，而非替代方案。

本地设置

Node 22+、pnpm；如需完整体验，需要 Postgres 和具备工具调用能力的 Ollama 模型（ollama pull llama3.1:8b——普通 llama3 无法可靠地发出工具调用）。

corepack enable && pnpm install
pnpm dev:api   # :3000
pnpm dev:web   # :4200, proxies /api → :3000

门检查：

pnpm --filter api build && pnpm --filter api lint && pnpm --filter api test && pnpm --filter api test:e2e
pnpm --filter web build && pnpm --filter web test

部署到 VPS

1. cp .env.example .env — 设置 POSTGRES_PASSWORD、MCP_READONLY_PASSWORD 和 JWT_SECRET（compose 缺少这些将拒绝启动）。确认 VPS 上的 ollama list 显示 llama3.1:8b。

2. docker compose up -d --build — web 仅绑定 127.0.0.1:8092。

3. 将 nginx/agent.build-with-deepak.com.conf 安装到主机 nginx 中，然后执行 certbot --nginx -d agent.build-with-deepak.com。

4. GET /api/health 是未认证的存活探测端点。

状态

• 通过 SDK 的内存传输实现真实的 MCP 服务器 + 客户端，三个工具，协议往返已由测试覆盖

• 智能体循环，包含实时 SSE 工具调用时间线、错误恢复反馈、步骤上限

• 两层 SQL 保护（守卫 + 专用只读 Postgres 角色）

• 演示账户认证端到端；注册 = 诚实的 501 即将推出

• 构建、lint、所有测试通过（API：25 个单元 + 5 个端到端；web：6 个）

• 尚未针对实时 Ollama/Postgres 运行 — 此环境两者均不具备；特别是智能体循环的 Ollama 工具调用路径，在面向任何人展示之前需要一次真实的 llama3.1 运行

• 尚未部署

• 注册/持久化账户 — 正在进行中（设计上以演示优先）