MCP Browse Me

MCP浏览我-Hello World

一个简单的模型上下文协议（MCP）“Hello World”应用程序，演示了基本的客户端-服务器通信。

概述

这个项目实现了一个最小的MCP服务器，它提供了一个“hello”工具和一个连接到服务器以调用此工具的客户端。服务器以个性化的问候消息进行响应。

特性

• MCP服务器：提供生成个性化问候语的“hello”工具
• MCP客户端：连接到服务器并调用hello工具
• 输入验证：使用Pydantic进行稳健的输入验证
• 综合测试：服务器和客户端组件的单元测试
• 类型安全：整个代码库中的完整类型注释

项目布局

├── data/                         # Chinook sample data
├── src/
│   ├── api/                      # FastAPI application that wraps the MCP client
│   └── mcp/
│       ├── client/               # Interactive MCP client logic
│       └── server/               # fastmcp + reference server implementations
├── docker-compose.yml            # Postgres + Chinook bootstrapper
├── pyproject.toml                # Project metadata and dependency list
└── README.md

设置

先决条件

• Python 3.8或更高版本
• uv（推荐）或pip用于包装管理
• Docker+Docker Compose用于可选的Chinook数据库

安装

1. 克隆或导航到项目目录：

   cd mcp-browse-me

1. 使用uv安装依赖项：

   uv sync

或者使用pip：

   pip install -e .

1. 对于开发依赖关系：

   uv sync --group dev

或者使用pip：

   pip install -e ".[dev]"

奇努克样本数据库

此存储库附带了Chinook示例数据 data/Chinook_PostgreSql.sql （为PostgreSQL做好准备）和 data/Chinook_Sqlite.sqliteDocker Compose定义(docker-compose.yml)提供了一个PostgreSQL实例来自动导入数据集。

启动数据库

docker compose up -d chinook-db

容器初始化为 chinook 数据库， chinook 用户，以及 chinook 密码。SQL脚本在第一次运行时自动加载。连接前确认容器健康：

docker compose ps chinook-db

连接和查询

使用 psql 在容器内部与数据库交互：

docker compose exec chinook-db psql -U chinook -d chinook

或者运行一次性查询：

docker compose exec chinook-db \
  psql -U chinook -d chinook \
  -c 'SELECT name, composer FROM track ORDER BY trackid LIMIT 5;'

您还可以使用连接字符串从本地工具进行连接 postgresql://chinook:chinook@localhost:5432/chinook.

提示： PostgreSQL会自动降低未加引号的标识符，因此Chinook表/列存储为 album, track, artist等等。以小写字母引用它们（或引用小写拼写）以避免 relation ... does not exist 错误。

配置MCP服务器

创建一个 .env 项目根目录中的文件（已提供）带有连接字符串，以便MCP服务器可以查询数据库：

DATABASE_URL=postgresql://chinook:chinook@localhost:5432/chinook

如果您更喜欢SQLite，请将URL指向 sqlite:///data/Chinook_Sqlite.sqlite.

一 OPENAI_API_KEY 条目已存在于 .env 对于未来的集成，如果您计划使用OpenAI工具扩展项目，请使用您自己的密钥填充它。

用法

运行MCP客户端

CLI会自动启动 src/mcp/server/fast_mcp_server.py，哪些负载 .env，连接到配置的数据库，并执行所请求的工具。

python src/mcp/client/main.py  

` 可以是： hello, goodbye, browse_files，或 query_db`.

或者，运行 PYTHONPATH=src/mcp python -m client.main 如果你喜欢 -m 样式命令。

示例：

python src/mcp/client/main.py hello Alice
python src/mcp/client/main.py browse_files .
python src/mcp/client/main.py query_db "SELECT name, composer FROM track LIMIT 5;"
python src/mcp/client/main.py list_tables ""

注： PostgreSQL将未加引号的标识符折叠为小写，因此Chinook脚本中的表/列名显示为 track, album, name等等。运行查询时使用小写字母（或引用确切的小写拼写）。

FastAPI端点

轻量级的API通过HTTP显示相同的MCP操作。

启动服务器（之后 uv sync/pip install -e .):

uvicorn src.api.main:app --reload --host 0.0.0.0 --port 3000

调用它 curl，HTTPie，或您选择的HTTP客户端：

curl -X POST http://127.0.0.1:3000/actions \
  -H "Content-Type: application/json" \
  -d '{"action":"hello","value":"Alice"}'

响应有效负载反映了CLI输出：

{
  "action": "hello",
  "value": "Alice",
  "response": "Hello, Alice!"
}

LangChain代理端点

代理支持的端点使用OpenAI+LangChain代表您调用MCP工具（需要 OPENAI_API_KEY 在 .env).

curl -X POST http://127.0.0.1:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"question":"List files in . and tell me what database tables exist"}'

代理将调用MCP工具，如 browse_files, list_tables，以及 query_db 根据需要回答问题。

状态语言图形聊天机器人（持久）

有状态代理将完整的聊天记录存储在Postgres中，并可以选择在Chroma中对交换进行索引，以进行相似性召回。

1. 确保聊天表存在（启动时自动运行，或手动应用）：

psql "$DATABASE_URL" -f data/ddl/chat_threads.sql

1. （可选）启动Chroma进行矢量调用（客户端固定为0.5.15以匹配捆绑的容器）：

docker compose up -d chromadb
export CHROMA_HOST=localhost
export CHROMA_PORT=8000

1. 调用有状态 /agent 端点，传递 session_id 仅当继续现有线程时：

curl -X POST http://127.0.0.1:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello, keep track of this chat", "session_id": "f2f96c03-01fd-4681-a8d1-bbca0996b0d6"}'

响应返回 session_id；在后续调用中重用它以维护历史记录。

运行测试

运行所有测试：

pytest

运行覆盖率测试：

pytest --cov=src/mcp --cov=src/api

运行特定的测试文件：

pytest tests/test_server.py
pytest tests/test_client.py

开发工具

格式代码：

black .

对导入进行排序：

isort .

类型检查：

mypy src

建筑

服务器(src/mcp/server/fast_mcp_server.py)

fastmcp服务器公开了几个工具：

• 说再见：Pydantic验证的友好问候
• 浏览文件：山宁泰目录列表，其中包含有用的错误消息
• 查询数据库：基于以下内容对Chinook数据库（SQLite或PostgreSQL）执行SQL DATABASE_URL
• 环境引导：负载 .env 自动使CLI/API调用共享DB凭据

客户(src/mcp/client)

客户端包包含可重用的操作助手(actions.py)以及CLI入口点(main.py):

• 会话管理：针对fastmcp服务器建立STDIO会话
• 工具发现：在发出请求之前记录可用工具
• 共享助手: run_client_action 驱动CLI和HTTP API层
• 错误处理：引发不受支持的操作和缺少服务器脚本的描述性错误

APIsrc/api/main.py)

FastAPI服务封装MCP客户端：

• 验证：确保传入 action 值与支持的工具列表匹配
• /操作终结点：异步执行MCP操作并返回文本结果
• /健康端点：容器编排的轻量级就绪性探针

通信流

1. 客户端将服务器作为子进程启动
2. 客户端与服务器建立基于STDIO的通信
3. 客户端初始化MCP会话
4. 客户端列出可用工具
5. 客户端使用提供的名称调用“hello”工具
6. 服务器验证输入并生成问候语
7. 客户端接收并显示响应

API 参考

Hello工具

名字: hello

描述：直呼某人的名字打招呼

输入架构:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the person to greet"
    }
  },
  "required": ["name"]
}

输出：带有个性化问候语的文本内容

测试

该项目包括全面的单元测试：

服务器测试(tests/test_server.py)

• 输入模型验证
• 工具列表功能
• 具有各种输入的工具调用处理
• 无效工具和参数的错误处理

客户端测试(tests/test_client.py)

• 工具调用成功
• 错误处理场景
• 边缘情况（空名称、连接错误）

测试夹具(tests/conftest.py)

• 常见测试数据和设置

贡献

1. 安装开发依赖项
2. 进行更改
3. 运行测试： pytest
4. 格式代码： black .
5. 对导入进行排序： isort .
6. 类型检查： mypy src

许可证

MIT许可证-您可以将其作为您自己的MCP应用程序的起点。

后续步骤

这是一个基本的Hello World示例。您可以通过以下方式扩展它：

• 向服务器添加更多工具
• 实施资源提供者
• 添加持久存储
• 创建更复杂的客户端交互
• 添加身份验证和安全功能