无结构化 MCP 服务器指南

安装说明

使用虚拟环境安装

1. 创建并激活 Python 虚拟环境：

   python -m venv ./.venv && source ./.venv/bin/activate
   

2. 安装项目依赖：

   pip install -r requirements.txt
   

快速安装（可选）

如果您只需要运行示例，可以使用以下命令直接获取所有必要文件：

make init

项目结构说明

.
├── CHANGELOG.md                  # 版本更新日志
├── README.md                     # 用户指南
├── requirements.txt             # 依赖管理文件
├── Makefile                      # 自动化构建脚本
├── uns_mcp/                     # 无结构化 MCP 服务器代码
│   ├── server.py                # 主服务入口
│   └── __init__.py              # 包初始化文件
└── minimal_client/               # 最小化客户端代码
    ├── client.py                 # 客户端主程序
    ├── __init__.py               # 包初始化文件
    └── tools/                    # 工具模块
        └── uns_structured.py     # 无结构化工具接口

快速启动

使用 Make 命令启动

make server           # 启动 MCP 服务器（SSE 模式）
make sse-server      # 启动 SSE 协议服务器
make sse-client      # 运行 SSE 模式的客户端
make stdio-server    # 启动 Stdio 协议服务器

手动启动

1. 启动 MCP 服务器（SSE 模式）：

   uv run python uns_mcp/server.py --host 127.0.0.1 --port 8080
   

2. 启动调试界面：

   mcp dev uns_mcp/server.py
   

配置说明

环境变量配置

• LOG_LEVEL：设置日志级别，可选值为 DEBUG、INFO、WARNING、ERROR，默认为 INFO。
• DEBUG_API_REQUESTS：启用或禁用 API 请求参数调试输出，默认为 False。

工具模块说明

1. minimal_client/tools/uns_structured.py：
   • 提供与无结构化服务交互的接口，包括文件处理、模型调用等功能。

调试工具

使用 Anthropic MCP 检查器

运行以下命令启动调试界面：

mcp dev uns_mcp/server.py

客户端终端访问

使用 @wonderwhy-er/desktop-commander 包添加终端访问权限：

1. 安装包：

   npx @wonderwhy-er/desktop-commander setup
   

2. 启动客户端时附加参数：

   uv run python minimal_client/client.py "http://127.0.0.1:8080" --terminal
   

已知问题

常见错误

• 端口冲突：如果启动失败提示端口被占用，请更换端口：

  uv run python uns_mcp/server.py --host 127.0.0.1 --port 8081
  

故障排除

日志查看

• 查看服务日志：

  tail -f uns_mcp/logs/server.log
  

附录

命令行工具

启动命令示例

# 启动 MCP 服务器（指定端口和 host）
uv run python uns_mcp/server.py --host 127.0.0.1 --port 8080

# 以调试模式启动
DEBUG=1 uv run python uns_mcp/server.py --host 127.0.0.1 --port 8080

客户端使用示例

uv run python minimal_client/client.py --help

高级主题

扩展开发

• 在 minimal_client/tools/ 目录下扩展更多工具模块。

自定义日志格式

修改 logging_config.yml 文件来自定义日志输出格式：

handlers:
  file_handler:
    class: logging.FileHandler
    filename: logs/server.log
    mode: a
    formatter: customFormatter
formatters:
  customFormatter:
    format: "%(asctime)s - %(levelname)s - %(message)s"

文档历史

修改记录

• v1.0：初始版本发布，包含基本功能和文档。
• v1.1：新增调试工具支持，优化日志系统。

如需更多帮助，请参考项目源码或联系维护团队。