Server Collection

这是一个包含多个 MCP (Model Context Protocol) 服务器的项目，每个服务器都有独立的功能和依赖。

🚀 特性

• 可扩展架构: 基于通用基类的模块化设计
• 统一日志管理: 使用 loguru 的高级日志系统
• 完善异常处理: 分层异常体系和统一错误处理
• 配置驱动: YAML 配置文件支持
• 多传输协议: 支持 stdio、SSE、HTTP 等传输方式
• 安全机制: 路径验证、敏感信息过滤等安全特性
• 开发友好: 详细的开发规范和示例代码

📁 项目结构

mcp-server/
├── common/                 # 通用模块
│   ├── __init__.py         # 模块导出
│   ├── logger.py           # 通用日志类
│   ├── exceptions.py       # 通用异常类
│   └── base_server.py      # 通用服务器基类
├── server/                 # 服务器实现
│   ├── __init__.py
│   └── demo_server.py      # 演示服务器
├── tool/                   # 工具函数
│   └── __init__.py
├── prompt/                 # 提示函数
│   └── __init__.py
├── resource/               # 资源函数
│   └── __init__.py
├── config/                 # 配置文件
│   └── demo_server.yml     # 演示服务器配置
├── workspace/              # 工作空间（运行时创建）
├── logs/                   # 日志目录（运行时创建）
├── pyproject.toml          # 项目配置
├── DEVELOPMENT_GUIDE.md    # 开发规范
└── README.md               # 项目说明

🛠️ 安装

环境要求

• Python 3.12+
• Windows/Linux/macOS

安装依赖

# 克隆项目
cd e:\project\ai_secretary\mcp-server

# 安装依赖
pip install -e .

# 或者使用 poetry（推荐）
poetry install

🚀 快速开始

1. 运行演示服务器

# 使用默认配置运行
python server/demo_server.py

# 指定端口和日志级别
python server/demo_server.py --port 8080 --log-level DEBUG

# 使用不同传输协议
python server/demo_server.py --transport sse

2. 测试服务器功能

演示服务器提供以下功能：

文件操作工具

• create_file: 创建文件
• read_file: 读取文件内容
• list_files: 列出目录文件

系统信息工具

• get_system_info: 获取系统信息
• get_environment_variables: 获取环境变量

通用工具（继承自基类）

• get_server_info: 获取服务器信息
• ping: 服务器心跳检测
• set_log_level: 动态设置日志级别

演示提示

• file_analysis: 文件分析提示
• system_health_check: 系统健康检查提示

演示资源

• workspace://files: 工作空间文件列表
• demo://status: 演示服务器状态

3. 配置服务器

编辑 config/demo_server.yml 文件来自定义服务器行为：

# 基本配置
server:
  name: "my-server"
  port: 8080

# 日志配置
logging:
  level: "INFO"
  file: true

# 文件操作配置
file_operations:
  work_directory: "./my_workspace"
  max_file_size: 5242880  # 5MB

🔧 开发新服务器

1. 创建服务器类

from common import BaseMCPServer, MCPError

class MyServer(BaseMCPServer):
    def __init__(self, **kwargs):
        super().__init__(
            name="my-server",
            description="我的自定义MCP服务器",
            version="1.0.0",
            **kwargs
        )
        
        # 注册自定义功能
        self._register_my_tools()
    
    def _register_my_tools(self):
        @self.mcp.tool()
        def my_custom_tool(param: str) -> dict:
            """自定义工具"""
            return {"result": f"处理参数: {param}"}

2. 添加配置文件

在 config/ 目录下创建对应的 YAML 配置文件。

3. 实现启动脚本

def main():
    server = MyServer()
    server.run()

if __name__ == "__main__":
    main()

📚 详细文档

• 开发规范 - 详细的开发指南和最佳实践
• API 文档 - API 接口文档（待创建）
• 配置参考 - 配置选项详细说明（待创建）

🏗️ 架构设计

核心组件

1. BaseMCPServer: 通用服务器基类

   • 统一的服务器生命周期管理
   • 内置日志、异常处理、配置管理
   • 预注册通用工具、提示、资源

2. MCPLogger: 通用日志类

   • 基于 loguru 的高级日志功能
   • 支持控制台和文件输出
   • 日志轮转和压缩

3. 异常体系: 分层异常处理

   • MCPError 基类
   • 特定场景的异常子类
   • 统一异常处理机制

设计原则

• 单一职责: 每个类和模块职责明确
• 开放封闭: 对扩展开放，对修改封闭
• 依赖倒置: 依赖抽象而非具体实现
• 配置驱动: 通过配置文件控制行为
• 安全第一: 内置安全机制和验证

🔒 安全特性

• 路径验证: 防止目录遍历攻击
• 文件大小限制: 防止资源耗尽
• 敏感信息过滤: 自动过滤敏感环境变量
• 输入验证: 严格的参数验证
• 错误信息脱敏: 避免泄露敏感信息

🧪 测试

# 运行单元测试
pytest tests/

# 运行集成测试
pytest tests/integration/

# 生成覆盖率报告
pytest --cov=common --cov=server tests/

📊 监控和调试

日志查看

# 查看实时日志
tail -f logs/demo-server.log

# 查看错误日志
grep "ERROR" logs/demo-server.log

性能监控

服务器内置性能监控功能，可通过以下方式查看：

• 使用 get_server_info 工具获取服务器状态
• 查看 server://logs/performance 资源
• 检查配置文件中的监控设置

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发规范

请遵循 DEVELOPMENT_GUIDE.md 中的开发规范：

• 代码风格：使用 black 格式化
• 类型注解：使用 mypy 检查
• 文档：使用 docstring 注释
• 测试：保持高测试覆盖率

📝 更新日志

v1.0.0 (2024-01-XX)

• ✨ 初始版本发布
• 🏗️ 实现基础架构和通用类
• 📚 完善文档和开发规范
• 🧪 添加演示服务器和示例

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Model Context Protocol - MCP 协议规范
• loguru - 优秀的 Python 日志库
• FastMCP - MCP 服务器框架

📞 支持

如果您遇到问题或有建议，请：

1. 查看 FAQ（待创建）
2. 搜索现有 Issues
3. 创建新的 Issue
4. 联系维护者

---

AI Secretary MCP Server - 让 AI 助手更强大 🚀