Zhiwen Assistant MCP

# 智文助手 MCP 配置指南 本文档详细说明如何在不同AI编辑器中配置智文助手的MCP服务器。 ## 📋 目录 - [什么是MCP](#什么是mcp) - [通用配置](#通用配置) - [编辑器特定配置](#编辑器特定配置) - [环境变量配置](#环境变量配置) - [故障排除](#故障排除) ## 🔍 什么是MCP MCP（Model Context Protocol）是一种标准化的协议，允许AI助手与各种工具和数据源进行交互。智文助手实现了MCP协议，使您能够在AI编辑器中直接调用其功能。 ## ⚙️ 通用配置 ### 基本配置结构 智文助手的MCP配置遵循以下基本结构： ```json { "mcpServers": { "zhiwen-assistant": { "command": "python", "args": [ "-m", "src.main", "--server" ], "cwd": "{PATH_TO_ZHIWEN_ASSISTANT}", "env": { "PYTHONPATH": "{PATH_TO_ZHIWEN_ASSISTANT}", "PYTHONIOENCODING": "utf-8" } } } } ``` ### 配置参数说明 | 参数 | 说明 | 必需 | |------|------|------| | `command` | 执行命令，通常是 `python` | 是 | | `args` | 命令参数列表 | 是 | | `cwd` | 智文助手项目根目录路径 | 是 | | `env` | 环境变量 | 可选 | ## 🖥️ 编辑器特定配置 ### 1. Cursor 编辑器 1. **打开设置**： - 按 `Ctrl+,` (Windows/Linux) 或 `Cmd+,` (macOS) - 或者通过菜单：文件 > 首选项 > 设置 2. **配置MCP服务器**： - 搜索 "MCP Servers" 或 "MCP" - 添加服务器配置 3. **完整配置示例**： ```json { "mcpServers": { "zhiwen-assistant": { "command": "python", "args": [ "-m", "src.main", "--server" ], "cwd": "e:/skills技能/智文助手", "env": { "PYTHONPATH": "e:/skills技能/智文助手", "PYTHONIOENCODING": "utf-8", "LOG_LEVEL": "INFO" } } } } ``` ### 2. Windsurf 编辑器 1. **打开设置**： - 点击右下角设置图标 - 选择 "Settings" 2. **配置MCP服务器**： - 找到 "MCP Configuration" 部分 - 添加服务器配置 3. **完整配置示例**： ```json { "mcpServers": { "zhiwen-assistant": { "command": "python", "args": [ "-m", "src.main", "--server" ], "cwd": "/path/to/zhiwen-assistant", "env": { "PYTHONPATH": "/path/to/zhiwen-assistant", "PYTHONIOENCODING": "utf-8", "LOG_LEVEL": "INFO" } } } } ``` ### 3. Claude Desktop 1. **找到配置文件**： - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` 2. **配置MCP服务器**： ```json { "mcpServers": { "zhiwen-assistant": { "command": "python", "args": [ "-m", "src.main", "--server" ], "env": { "PYTHONPATH": "/path/to/zhiwen-assistant", "PYTHONIOENCODING": "utf-8" } } } } ``` 3. **重启Claude Desktop**使配置生效 ## 🌍 环境变量配置 智文助手支持通过环境变量进行详细配置。您可以： 1. **使用.env文件**（推荐）： - 复制项目根目录下的 `.env.example` 为 `.env` - 根据需要修改配置 2. **直接在MCP配置中设置**： ```json "env": { "PYTHONPATH": "{PATH_TO_ZHIWEN_ASSISTANT}", "PYTHONIOENCODING": "utf-8", "LOG_LEVEL": "DEBUG", "LOG_DIR": "./logs", "MAX_CONCURRENT_TASKS": "10", "DEFAULT_LANGUAGE": "zh-CN", "GENERATION_TIMEOUT": "180", "VERBOSE": "true" } ``` ### 环境变量说明 | 变量 | 默认值 | 说明 | |------|--------|------| | `PYTHONPATH` | - | 项目路径（必需） | | `PYTHONIOENCODING` | utf-8 | Python IO编码 | | `LOG_LEVEL` | INFO | 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL） | | `LOG_DIR` | ./logs | 日志目录 | | `MAX_CONCURRENT_TASKS` | 5 | 最大并发任务数 | | `DEFAULT_LANGUAGE` | zh-CN | 默认文档语言 | | `GENERATION_TIMEOUT` | 120 | 文档生成超时时间（秒） | | `VERBOSE` | false | 是否显示详细输出 | ## 🔧 自定义启动脚本 如果您的环境需要特殊配置，可以创建自定义启动脚本： ### Windows批处理脚本示例 (start-zhiwen.bat) ```batch @echo off set PYTHONPATH=e:/skills技能/智文助手 set PYTHONIOENCODING=utf-8 set LOG_LEVEL=INFO cd /d "e:/skills技能/智文助手" python -m src.main --server %* ``` 然后在MCP配置中使用： ```json { "mcpServers": { "zhiwen-assistant": { "command": "e:/skills技能/智文助手/start-zhiwen.bat", "args": [] } } } ``` ### Shell脚本示例 (start-zhiwen.sh) ```bash #!/bin/bash export PYTHONPATH="/path/to/zhiwen-assistant" export PYTHONIOENCODING="utf-8" export LOG_LEVEL="INFO" cd "/path/to/zhiwen-assistant" python -m src.main --server "$@" ``` 然后在MCP配置中使用： ```json { "mcpServers": { "zhiwen-assistant": { "command": "/path/to/zhiwen-assistant/start-zhiwen.sh", "args": [] } } } ``` ## 🐛 故障排除 ### 常见问题及解决方案 1. **模块导入错误** ``` ModuleNotFoundError: No module named 'src' ``` - 确保 `PYTHONPATH` 环境变量正确设置 - 检查工作目录（cwd）是否正确 2. **权限错误** ``` PermissionError: [Errno 13] Permission denied ``` - 确保Python有足够的权限访问项目目录 - 在Windows上，可能需要以管理员身份运行编辑器 3. **端口冲突** ``` OSError: [Errno 48] Address already in use ``` - 更改配置中的端口号 - 或关闭占用端口的程序 4. **Python版本不兼容** ``` SyntaxError: invalid syntax ``` - 确保使用Python 3.8或更高版本 - 可以在MCP配置中指定Python路径： ```json "command": "/usr/bin/python3.9" ``` 5. **依赖包缺失** ``` ImportError: No module named 'fastmcp' ``` - 确保已安装所有依赖： ```bash pip install -r requirements.txt ``` - 或在MCP配置中指定虚拟环境： ```json "command": "/path/to/venv/bin/python" ``` ### 调试技巧 1. **启用详细日志**： ```json "env": { "LOG_LEVEL": "DEBUG", "VERBOSE": "true" } ``` 2. **测试命令行运行**： ```bash cd /path/to/zhiwen-assistant python -m src.main --server ``` 3. **检查MCP服务器列表**： 在编辑器中查看MCP服务器状态，确认智文助手是否已正确加载。 ## 📚 更多资源 - [智文助手安装指南](INSTALL.md) - [智文助手使用指南](USAGE.md) - [智文助手API文档](API.md) - [MCP协议文档](https://modelcontextprotocol.io) --- *最后更新: 2025年12月19日*