# MCP 服务器集合

这是一个包含多个 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

### 安装依赖

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

# 安装依赖
pip install -e .

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

## 🚀 快速开始

### 1. 运行演示服务器

```bash
# 使用默认配置运行
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` 文件来自定义服务器行为：

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

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

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

## 🔧 开发新服务器

### 1. 创建服务器类

```python
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. 实现启动脚本

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

if __name__ == "__main__":
    main()
```

## 📚 详细文档

- [开发规范](DEVELOPMENT_GUIDE.md) - 详细的开发指南和最佳实践
- [API 文档](docs/api.md) - API 接口文档（待创建）
- [配置参考](docs/configuration.md) - 配置选项详细说明（待创建）

## 🏗️ 架构设计

### 核心组件

1. **BaseMCPServer**: 通用服务器基类
   - 统一的服务器生命周期管理
   - 内置日志、异常处理、配置管理
   - 预注册通用工具、提示、资源

2. **MCPLogger**: 通用日志类
   - 基于 loguru 的高级日志功能
   - 支持控制台和文件输出
   - 日志轮转和压缩

3. **异常体系**: 分层异常处理
   - MCPError 基类
   - 特定场景的异常子类
   - 统一异常处理机制

### 设计原则

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

## 🔒 安全特性

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

## 🧪 测试

```bash
# 运行单元测试
pytest tests/

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

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

## 📊 监控和调试

### 日志查看

```bash
# 查看实时日志
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](DEVELOPMENT_GUIDE.md) 中的开发规范：

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

## 📝 更新日志

### v1.0.0 (2024-01-XX)

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

## 📄 许可证

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

## 🙏 致谢

- [Model Context Protocol](https://github.com/modelcontextprotocol) - MCP 协议规范
- [loguru](https://github.com/Delgan/loguru) - 优秀的 Python 日志库
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务器框架

## 📞 支持

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

1. 查看 [FAQ](docs/faq.md)（待创建）
2. 搜索现有 [Issues](../../issues)
3. 创建新的 Issue
4. 联系维护者

---

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