一个使用模型上下文协议 (MCP) 的 LLM 代理工具集的最小化演示。
该仓库包含小型 Node.js/TypeScript 和 Python 示例，展示代理如何：
从 MCP 服务器发现工具；
将这些工具暴露给 LLM；
让模型请求工具调用；
通过 MCP 执行这些调用；
将工具结果返回给模型；
持续循环直到模型生成最终响应。
重要提示： 这仅是演示代码。它不是生产代码，不应被视为安全、健壮或完整的代理框架。
该仓库的目的是让基于 MCP 的代理工具集机制易于检查。
在高层面上：
User
|
v
LLM
|
| tool request
v
Agent Harness
|
v
MCP Client
|
v
MCP Server
|
v
Tool Implementation
|
v
Tool Result
|
+------------------> LLM职责被有意分离：
LLM - decides what it thinks should happen
Harness - manages the agent loop and conversation state
MCP - standardises tool discovery and invocation
Tools - perform the actual deterministic operationsMCP 不决定应调用哪个工具。
工具选择仍然是模型的决定，除非周围应用程序明确约束或覆盖它。
Related MCP server: MCP Server Scaffold
许多代理框架的术语可能掩盖实际发生的事情。
基本的工具集循环不过如此：
call model
|
v
did it request a tool?
|
/ \
no yes
| |
answer execute tool
|
v
return result
|
+----> call model again该仓库保持这一机制可见，而不是将其隐藏在一个大型代理框架后面。
典型布局如下：
.
├── node/
│ ├── package.json
│ └── src/
│ ├── agent.ts
│ └── server.ts
│
└── python/
├── agent.py
└── server.py确切的目录名称可以更改，不影响架构。
演示服务器暴露了三个故意简化的假设性工具：
get_github_activity
get_site_content
contact_scott这些仅是示例，旨在演示：
工具发现；
工具模式；
工具描述；
参数；
执行；
结果处理。
它们不旨在代表真实后端。
Node.js 20+
OpenAI API 密钥
安装依赖：
npm install设置 API 密钥：
export OPENAI_API_KEY="sk-..."运行代理：
npm startMCP 服务器由代理通过 stdio 传输自动启动。
您无需单独运行服务器。
示例输出：
MCP tools: [
'get_github_activity',
'get_site_content',
'contact_scott'
]
MODEL REQUESTED TOOL: get_github_activity
ARGUMENTS: {}
MCP RESULT:
...
FINAL ANSWER
------------
Scott has recently been working on...Python 3.10+
OpenAI API 密钥
创建虚拟环境：
python3 -m venv .venv
source .venv/bin/activate升级打包工具：
python3 -m pip install --upgrade pip setuptools wheel安装依赖：
pip install "mcp>=2,<3" openai设置 API 密钥：
export OPENAI_API_KEY="sk-..."运行：
python3 agent.pyPython 版本作为交互式 CLI 聊天机器人运行：
MCP tools: ['get_github_activity', 'get_site_content', 'contact_scott']
Chat started.
Type /quit to exit.
You> hello
Assistant> Hello! How can I help?
You> What has Scott been working on?
[tool] get_github_activity({})
[result] ...
Assistant> Scott has recently been working on...Python 客户端在轮次之间保留对话历史，并将正常响应流式输出到终端。
这些示例使用基于 stdio 的 MCP。
代理将 MCP 服务器作为子进程启动：
agent
|
+---- stdin/stdout ---- MCP server这对于本地实验很方便，因为：
没有单独的服务器守护进程；
没有 HTTP 端点；
没有端口配置；
没有额外的身份验证层。
一个重要后果是 MCP stdio 服务器不得将任意调试输出写入 stdout。
stdout 属于 MCP 协议。
请改用 stderr 进行诊断。
例如：
print("debug information", file=sys.stderr)或在 TypeScript 中：
console.error("debug information");基本的工具集逻辑是：
while True:
response = await model(...)
calls = find_tool_calls(response)
if not calls:
return
for call in calls:
result = await mcp.call_tool(
call.name,
call.arguments,
)
add_result_to_context(result)真实的工具集可能还会实现：
permissions
timeouts
tool allowlists
human approval
rate limits
cost limits
logging
tracing
context pruning
retry policies
authentication
authorization
sandboxing
validation
auditing
error recovery此演示有意很少实现这些。
工具集不需要硬编码的实现列表。
相反，它向 MCP 服务器询问其可用工具。
概念上：
MCP server
|
| tools/list
v
Agent harness然后工具集将结果：
name
description
input schema暴露给模型。
如果 MCP 服务器后来添加了另一个工具，工具集可以在不添加另一个自定义分发分支的情况下发现它。
这是 MCP 提供的主要架构优势之一。
这一点很重要。
假设服务器提供：
contact_scott描述说当有人想雇佣或联系 Scott 时应使用它。
用户可能会说：
Can I hire Scott for consulting?期望的模型行为是：
contact_scott(...)但 LLM 可能反而产生普通的对话响应。
MCP 不能解决这个问题。
决定：
Does this natural-language request imply this tool?仍然是概率性的模型推理。
工具描述改善了路由行为，但它们不创建形式上的保证。
如果某个动作必须确定性地发生，该要求应在普通应用程序逻辑中强制执行，而不是仅依赖 LLM 指令。
一旦模型请求了工具，系统的其余部分可以是确定性的：
model requests tool
|
v
validate arguments
|
v
check permission
|
v
execute function
|
v
return result但初始的语义决定可能仍然是概率性的。
这种区别对于具有重大后果的动作尤其重要，例如：
sending money
deleting data
changing permissions
submitting legal information
making purchases
sending messages
altering customer records生产系统应在具有有意义后果的动作周围放置明确的确定性控制。
Python CLI 使用流式输出，因此文本在生成时即出现。
没有流式输出：
You> explain virtual memory
<wait>
Assistant> Virtual memory is...有流式输出：
You> explain virtual memory
Assistant> Virtual memory is...流式输出主要改善了感知延迟。
使用工具的轮次可能仍然需要更长时间，因为它们可能需要多个模型请求：
model request
|
v
tool call
|
v
MCP execution
|
v
tool result
|
v
second model request该仓库有意保持最小化。
它不提供生产代理系统所期望的安全保障。
在其他方面，生产代码需要考虑：
身份验证；
授权；
秘密管理；
恶意工具输入；
提示注入；
输出验证；
工具结果验证；
模式强制执行；
资源限制；
网络隔离；
子进程安全；
用户确认重要操作；
审计日志；
重试行为；
故障恢复；
成本控制；
上下文增长；
模型版本变化；
API 版本变化；
依赖锁定；
可观测性；
测试和评估；
隐私和数据保留要求。
不要将示例 MCP 服务器直接暴露给不受信任的用户，也不要使用示例的 contact_scott 模式进行真实通信，除非添加了适当的验证、身份验证、持久化、滥用保护和错误处理。
再次强调：
此仓库是用于学习和实验的演示代码，而非生产部署。
将各层分开是有用的：
MCP
!= LLM
MCP
!= agent
MCP
!= tool-selection logic
MCP
!= security policyMCP 是用于暴露和调用能力的协议。
工具集管理模型/工具循环。
模型执行语言推理。
底层工具执行实际工作。
一个有用的心智模型是：
Agent System
=
Model
+
Harness
+
Tools
+
Context
+
PolicyMCP 在这些组件中的一些之间提供标准接口。
对于一个应用程序中的三个本地函数，您完全可以这样做。
例如：
TOOLS = {
"foo": foo,
"bar": bar,
}可能比 MCP 更简单。
当能力需要在多个客户端之间可重用时，MCP 变得更有趣：
MCP Server
/ | \
/ | \
/ | \
CLI agent IDE website工具提供者变得独立于任何特定的模型宿主或应用程序。
这是引入 MCP 的主要架构原因。
一旦基本 CLI 工作正常，有用的实验包括：
run the same prompt repeatedly
change tool descriptions
change models
change system instructions
record selected tools
measure latency
measure token usage
add approval gates
add deliberately ambiguous prompts
add multiple MCP servers
introduce tool failures
introduce malformed results
limit maximum agent steps一个特别有用的测试是记录：
prompt
selected tool
arguments
number of model calls
latency
final response跨多次运行。
这样可以检查模型带来了多少变化，以及工具集可以控制多少行为。
为您的仓库添加适当的许可证。
此代码的目的不是提供另一个大型代理框架。
而是清晰地展示机制，使核心过程可以被理解：
Model proposes.
Harness controls.
MCP connects.
Tools execute.所有更复杂的东西都建立在此基础上。
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Synaptechlabs/mcp-minimal-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server