Dirt (Atomic Germ)

污垢：可插拔MCP聊天客户端

一个基于FastAPI的MCP客户端，可以自动启动配置的stdio MCP服务器，发现它们的工具，并将它们暴露给聊天（通过Ollama）和REST/CLI。随附中定义的示例服务器 mcp_config.json （奥拉玛咨询、织梦者、创造性冥想、共振引擎、mcp桥）。

特性

• 自动启动+发现：从env/JSON配置启动MCP服务器，然后调用 tools/list 以了解确切的工具名称。
• 聊天工具调用：模型可以通过调用MCP工具 call_mcp_tool 图式；工具名称被注入到系统提示符中。
• REST+CLI：通过FastAPI端点或 mcp_cli.py.
• 配置灵活性：从加载 mcp_config.json 或环境变量；支持具有自定义env/args的stdio服务器。
• 测试流量：系统测试启动真实的服务器，发现工具，并进行端到端的工具调用。

建筑

1. MCP客户端 (app/mcp_client.py)：管理stdio MCP服务器、JSON-RPC、， tools/list，以及工具调用。
2. Web API (app/main.py)：用于聊天、服务器生命周期和工具调用的FastAPI端点；将发现的工具名称注入聊天提示符。
3. 命令行界面 (app/mcp_cli.py)：用于列出/启动/停止服务器和调用工具的便利包装器。

安装

先决条件

• Python 3.12+
• 已安装的MCP服务器可在PATH上访问（该仓库包含一个示例 mcp_config.json 指向stdio服务器，如 dream-weaver 和 creative-meditate).

安装Python依赖项

pip install -e .

配置

方法1：环境变量

设置环境变量以配置MCP服务器：

# List of servers to load
export MCP_SERVERS="ollama-consult,dream-weaver,creative-meditate"

# Configuration for each server
export MCP_SERVER_OLLAMA_CONSULT_COMMAND="mcp-ollama-consult"
export MCP_SERVER_OLLAMA_CONSULT_ARGS="[]"
export MCP_SERVER_OLLAMA_CONSULT_ENV='{"MEMORY_DIR": "/path/to/memory", "MCP_AUTO_MODEL_SETTINGS": "1"}'

export MCP_SERVER_DREAM_WEAVER_COMMAND="dream-weaver"
export MCP_SERVER_DREAM_WEAVER_ARGS="[]"
export MCP_SERVER_DREAM_WEAVER_ENV='{"MEMORY_DIR": "/path/to/memory"}'

# Optional: Specify node_modules path for local installations
export MCP_SERVER_MY_SERVER_NODE_MODULES="/path/to/project/node_modules"

方法2:JSON配置文件

创建一个 mcp_config.json 文件：

{
  "servers": {
    "ollama-consult": {
      "command": "mcp-ollama-consult",
      "args": [],
      "env": {
        "MEMORY_DIR": "/home/user/.mcp-group/",
        "KNOWLEDGE_BASE_PATH": "/home/user/.mcp-group/",
        "MCP_AUTO_MODEL_SETTINGS": "1"
      },
      "node_modules_path": null
    },
    "dream-weaver": {
      "command": "dream-weaver",
      "args": [],
      "env": {
        "MEMORY_DIR": "/home/user/.mcp-group/",
        "KNOWLEDGE_BASE_PATH": "/home/user/.mcp-group/"
      },
      "node_modules_path": null
    }
  }
}

用法

运行API+聊天

python app/main.py

• 聊天端点： POST /chat （使用Olama；模型可以返回 call_mcp_tool 操作，服务器将执行这些操作）。
• MCP管理： GET /mcp/servers, POST /mcp/servers/start, POST /mcp/servers/stop, POST /mcp/tools/call, GET /mcp/servers/{server_name}/config.

例子：

# List servers
curl http://localhost:8000/mcp/servers

# Start a server
curl -X POST http://localhost:8000/mcp/servers/start \
  -H "Content-Type: application/json" \
  -d '{"server_name": "ollama-consult"}'

# Call a tool
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "ollama-consult",
    "tool_name": "consult_ollama",
    "arguments": {"prompt": "Hello, world!"}
  }'

CLI工具

# List configured servers
python app/mcp_cli.py list

# Start a server
python app/mcp_cli.py start ollama-consult

# Call a tool
python app/mcp_cli.py call ollama-consult consult_ollama --args '{"prompt": "Hello, world!"}'

Python API

在Python代码中直接使用MCP客户端：

from mcp_client import initialize_mcp_client

# Initialize with environment variables
client = initialize_mcp_client()

# Or initialize with JSON config
client = initialize_mcp_client("mcp_config.json")

# Start a server
client.start_server("ollama-consult")

# Call a tool
result = client.call_tool("ollama-consult", "consult_ollama", {
    "prompt": "Hello, world!",
    "model": "kimi-k2-thinking:cloud"
})

# Stop a server
client.stop_server("ollama-consult")

MCP服务器兼容性

与遵循协议和支持的stdio MCP服务器配合使用 tools/list。服务器作为具有可选env/args的子进程启动。

环境变量引用

全局配置

• MCP_SERVERS：要加载的以逗号分隔的服务器名称列表

每台服务器配置

对于每个命名的服务器 SERVER_NAME:

• MCP_SERVER_{SERVER_NAME}_COMMAND：运行服务器的可执行命令
• MCP_SERVER_{SERVER_NAME}_ARGS：命令行参数的JSON数组
• MCP_SERVER_{SERVER_NAME}_ENV：服务器环境变量的JSON对象
• MCP_SERVER_{SERVER_NAME}_NODE_MODULES：node_modules目录的路径（可选）

环境设置示例

# Global config
export MCP_SERVERS="ollama-consult,dream-weaver,resonance-engine"

# Ollama Consult server
export MCP_SERVER_OLLAMA_CONSULT_COMMAND="mcp-ollama-consult"
export MCP_SERVER_OLLAMA_CONSULT_ARGS="[]"
export MCP_SERVER_OLLAMA_CONSULT_ENV='{"MEMORY_DIR": "/tmp/mcp", "MCP_AUTO_MODEL_SETTINGS": "1"}'

# Dream Weaver server
export MCP_SERVER_DREAM_WEAVER_COMMAND="dream-weaver"
export MCP_SERVER_DREAM_WEAVER_ARGS="[]"
export MCP_SERVER_DREAM_WEAVER_ENV='{"MEMORY_DIR": "/tmp/mcp"}'

# Resonance Engine server
export MCP_SERVER_RESONANCE_ENGINE_COMMAND="resonance-engine"
export MCP_SERVER_RESONANCE_ENGINE_ARGS="[]"
export MCP_SERVER_RESONANCE_ENGINE_ENV='{"MEMORY_DIR": "/tmp/mcp"}'

发展

添加新的MCP服务器

1. 安装Node.js包： npm install -g your-mcp-server
2. 通过环境变量或JSON配置添加配置
3. 系统将自动发现并加载服务器

扩展客户端

这 MCPClient 可以扩展到其他运输或健康监测；工具发现目前依赖于 tools/list.

故障排除

服务器无法启动

1. 检查是否安装了Node.js包： npm list -g your-server
2. 验证命令是否正确： which your-server-command
3. 检查环境变量是否设置正确
4. 在控制台输出中查看服务器日志

工具调用失败

1. 确保服务器已启动： python mcp_cli.py list
2. 验证工具名称是否正确
3. 检查参数格式是否符合工具的要求
4. 审查MCP协议合规性

权限问题

1. 确保用户对Node.js二进制文件具有执行权限
2. 检查配置路径的文件系统权限
3. 验证服务器是否可以写入配置的目录

许可证

这个项目是开源的。请参阅各个MCP服务器许可证以了解其条款。