Pero MCP Server
README.md
<div align="center">
# 🚀 Pero MCP Server
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](#ssh-客户端)
[](#app-store-connect-集成)
*一个功能强大的 Model Context Protocol (MCP) 服务器*
**集成多种功能 • SSH 连接管理 • App Store Connect API 集成**
---
</div>
## ✨ 功能特性
<table>
<tr>
<td width="50%">
### 🔐 SSH 客户端
- 🔗 **SSH 连接管理** - 安全的远程连接
- ⚡ **远程命令执行** - 快速执行远程操作
- 📁 **文件传输功能** - 双向文件传输支持
</td>
<td width="50%">
### 🍎 App Store Connect 集成
- 📱 **应用列表获取** - 管理你的应用
- 👥 **团队成员管理** - 协作团队管理
- 🧪 **TestFlight 管理工具** - 测试版本管理
</td>
</tr>
</table>
## 🛠️ 安装和配置
### 📋 环境要求
-  Python 3.8+
- 📦 相关依赖包（见 requirements.txt）
### 💻 安装依赖
```bash
pip install -r requirements.txt
```
## ⚙️ MCP 客户端配置
在你的 MCP 客户端（如 Claude Desktop）配置文件中添加以下配置：
### 📡 传输方式配置说明
MCP 服务器支持多种传输方式，可以通过以下参数进行配置：
<summary>🔧 传输参数说明</summary>
| 参数名 | 描述 | 默认值 | 示例 |
|-------------|-----------------|-----------|--------------------------|
| `transport` | 传输协议类型 | `stdio` | `stdio`, `http` |
| `host` | 服务器主机地址（HTTP模式） | `0.0.0.0` | `127.0.0.1`, `localhost` |
| `port` | 服务器端口（HTTP模式） | `8000` | `8000`, `8080` |
**📋 传输方式说明：**
- 🔤 **stdio** (默认)：标准输入输出方式，适合本地开发和测试
- 🌐 **http**：streamable-http 方式，适合网络通信和远程访问
### 🏠 本地开发环境配置
```json
{
"servers": {
"pero-mcp-server-local": {
"command": "python",
"args": [
"path/to/pero-mcp-server"
],
"env": {
"SSH_HOST": "your_ssh_host",
"SSH_USERNAME": "your_username",
"SSH_PORT": "22",
"SSH_PASSWORD": "your_password",
"APPSTORE_KEY_ID": "your_key_id",
"APPSTORE_ISSUER_ID": "your_issuer_id",
"APPSTORE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nyour_private_key_content\n-----END PRIVATE KEY-----"
}
}
}
}
```
### 🌐 远程生产环境配置
```json
{
"servers": {
"pero-mcp-server-remote": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/peroperogames/pero-mcp-server",
"pero-mcp-server"
],
"env": {
"SSH_HOST": "your_production_ssh_host",
"SSH_USERNAME": "your_ssh_username",
"SSH_PORT": "22",
"SSH_PASSWORD": "your_ssh_password",
"APPSTORE_KEY_ID": "your_appstore_key_id",
"APPSTORE_ISSUER_ID": "your_appstore_issuer_id",
"APPSTORE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nyour_private_key_content\n-----END PRIVATE KEY-----"
}
}
}
}
```
> - 🔄 无需本地安装和配置，自动获取最新代码
> - 🏭 适合生产环境或团队协作使用
## 📝 环境变量说明
<details>
<summary>🔐 SSH 配置</summary>
| 变量名 | 描述 | 示例 |
|----------------|---------------|-----------------|
| `SSH_HOST` | SSH 服务器主机地址 | `192.168.1.100` |
| `SSH_USERNAME` | SSH 用户名 | `admin` |
| `SSH_PORT` | SSH 端口（默认 22） | `22` |
| `SSH_PASSWORD` | SSH 密码 | `your_password` |
</details>
<details>
<summary>🍎 App Store Connect 配置</summary>
| 变量名 | 描述 | 必需 |
|------------------------|-----------------------------|----|
| `APPSTORE_KEY_ID` | App Store Connect API 密钥 ID | ✅ |
| `APPSTORE_ISSUER_ID` | 发行者 ID | ✅ |
| `APPSTORE_PRIVATE_KEY` | 私钥内容（完整的 PEM 格式） | ✅ |
| `APPSTORE_APP_ID` | 应用 ID | ❌ |
</details>
## 🔧 可用工具
<div align="center">
| 分类 | 工具名称 | 功能描述 |
|------------------|----------------------|----------------------------|
| 🔐 **SSH** | `ssh_connect` | 🔗 建立 SSH 连接 |
| 🔐 **SSH** | `ssh_execute` | ⚡ 执行远程命令 |
| 🔐 **SSH** | `ssh_upload` | ⬆️ 上传文件 |
| 🔐 **SSH** | `ssh_download` | ⬇️ 下载文件 |
| 🍎 **App Store** | `configure_appstore` | ⚙️ 配置 App Store Connect 凭据 |
| 🍎 **App Store** | `get_apps` | 📱 获取应用列表 |
| 🍎 **App Store** | `get_team_members` | 👥 获取团队成员信息 |
</div>
## 📚 可用资源
### 🔐 SSH 资源
- `ssh://status` - 📊 SSH 连接状态
- `ssh://info` - ℹ️ SSH 连接信息
### 🍎 App Store Connect 资源
- `appstore://apps` - 📱 应用列表
- `appstore://members` - 👥 团队成员列表
## 💡 可用提示模板
### 🔐 SSH 提示
- `ssh_troubleshoot` - 🔧 SSH 连接故障排除
### 🍎 App Store Connect 提示
- `manage_testflight` - 🧪 TestFlight 管理操作
## 🚀 使用示例
启动服务器后，你可以在 MCP 客户端中使用以下命令：
```python
# 🔐 SSH 操作
ssh_connect()
ssh_execute(command="ls -la")
# 🍎 App Store Connect 操作
get_apps()
get_team_members()
```
## 👨💻 开发指南
### 📁 项目结构
```
pero-mcp-server/
├── 📄 pero_mcp_server.py # 主服务器入口文件
├── ⚙️ pyproject.toml # 项目配置文件
├── 📦 requirements.txt # Python依赖包
├── 📖 README.md # 项目说明文档
├── 📝 .env.example # 环境变量示例文件
├── 🚫 .gitignore # Git忽略文件配置
├── 🐍 .venv/ # Python虚拟环境
└── 📂 clients/ # MCP客户端实现
├── 🔧 __init__.py
├── 🎯 i_mcp_client.py # 客户端接口定义
├── 🔐 ssh/ # SSH客户端模块
│ ├── 🔧 __init__.py
│ ├── 💻 ssh_mcp_client.py # SSH MCP客户端实现
│ └── 📊 models.py # SSH数据模型
└── 🍎 appstoreconnect/ # App Store Connect客户端模块
├── 🔧 __init__.py
├── 📱 appstore_connect_mcp_client.py # App Store Connect MCP客户端
└── 📊 models.py # App Store Connect数据模型
```
### 🔧 开发环境设置
<details>
<summary>点击展开详细步骤</summary>
1. **📥 克隆项目**
```bash
git clone <repository-url>
cd pero-mcp-server
```
2. **🐍 创建虚拟环境**
```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate
```
3. **📦 安装依赖**
```bash
pip install -r requirements.txt
```
4. **⚙️ 设置环境变量**
创建 `.env` 文件或在系统中设置环境变量：
```bash
SSH_HOST=your_ssh_host
SSH_USERNAME=your_username
SSH_PORT=22
SSH_PASSWORD=your_password
APPSTORE_KEY_ID=your_key_id
APPSTORE_ISSUER_ID=your_issuer_id
APPSTORE_PRIVATE_KEY=your_private_key
```
</details>
### 🏗️ 代码架构
#### 1. 📦 客户端架构 (clients/)
- **🎯 i_mcp_client.py**: 定义了MCP客户端的通用接口
- **🔐 ssh/**: SSH功能的客户端实现，包含SSH连接管理和远程操作
- **🍎 appstoreconnect/**: App Store Connect功能的客户端实现，处理App Store API交互
#### 2. 🚀 主服务器 (pero_mcp_server.py)
- 🔧 集成所有客户端组件
- 🎯 提供统一的MCP服务器入口
- ⚡ 处理工具调用、资源访问和提示模板
- 🔄 管理不同客户端之间的协调
### 📜 开发规范
<details>
<summary>🎨 代码风格</summary>
- ✅ 使用Python类型提示
- 📝 遵循PEP 8代码规范
- 🏷️ 使用有意义的变量和函数名
- 📖 添加适当的文档字符串
</details>
<details>
<summary>⚠️ 错误处理</summary>
- 🛡️ 使用适当的异常处理
- 💬 提供清晰的错误消息
- 📋 记录关键操作的日志
</details>
<details>
<summary>🧪 测试</summary>
- ✅ 为新功能编写单元测试
- 🔍 确保现有测试通过
- 🎯 测试错误情况和边界条件
</details>
### ➕ 添加新功能
要添加新功能，需要实现 `IMCPClient` 接口。以下是完整的实现步骤：
<details>
<summary>🛠️ 第一步：创建客户端类</summary>
```python
from clients.mcp_client_interface import IMCPClient
from typing import Any
import mcp.types as types
class YourNewMCPClient(IMCPClient):
"""你的新功能客户端"""
def __init__(self):
"""初始化客户端"""
# 初始化你的客户端状态
pass
def register_tools(self, mcp: Any) -> None:
"""注册工具到FastMCP实例"""
@mcp.tool()
async def your_new_tool(arguments: dict) -> list[types.TextContent]:
"""
你的新工具描述
Args:
arguments: 工具参数字典
Returns:
工具执行结果
"""
# 实现你的工具逻辑
result = await self._execute_your_logic(arguments)
return [types.TextContent(type="text", text=result)]
def register_resources(self, mcp: Any) -> None:
"""注册资源到FastMCP实例"""
@mcp.resource("your_scheme://your_resource")
async def read_your_resource(uri: str) -> str:
"""
读取你的资源
Args:
uri: 资源URI
Returns:
资源内容
"""
# 处理资源读取逻辑
return await self._read_resource_content(uri)
def register_prompts(self, mcp: Any) -> None:
"""注册提示模板到FastMCP实例"""
@mcp.prompt()
async def your_prompt_template(arguments: dict) -> types.PromptMessage:
"""
你的提示模板
Args:
arguments: 提示参数
Returns:
提示消息
"""
# 生成提示内容
content = await self._generate_prompt_content(arguments)
return types.PromptMessage(
role="user",
content=types.TextContent(type="text", text=content)
)
async def _execute_your_logic(self, arguments: dict) -> str:
"""实现你的具体业务逻辑"""
# 在这里实现你的功能逻辑
pass
async def _read_resource_content(self, uri: str) -> str:
"""读取资源内容的具体实现"""
# 在这里实现资源读取逻辑
pass
async def _generate_prompt_content(self, arguments: dict) -> str:
"""生成提示内容的具体实现"""
# 在这里实现提示生成逻辑
pass
```
</details>
<details>
<summary>📁 第二步：放置客户端文件</summary>
由于项目具有自发现机制，你只需要将新客户端放在正确的位置即可：
为新功能创建独立的模块目录：
```
clients/
└── yournew/ # 你的新功能模块
├── __init__.py
├── your_new_mcp_client.py # 主客户端实现
├── models.py # 数据模型（如果需要）
└── utils.py # 工具函数（如果需要）
```
**🔍 自动发现机制**
服务器会自动扫描 `clients/` 目录下的所有子目录，查找继承自 `IMCPClient` 的类并自动注册。你无需手动修改主服务器代码。
</details>
<details>
<summary>🚀 第三步：重启服务器</summary>
完成客户端实现后，重启MCP服务器即可自动加载新功能：
```bash
python pero_mcp_server.py
```
服务器启动时会自动发现并注册你的新客户端。
</details>
#### 2. 🎯 IMCPClient接口说明
`IMCPClient` 是所有MCP客户端必须实现的抽象基类，包含以下方法：
- **`register_tools(mcp)`** 🔧: 注册工具函数，这些工具可以被MCP客户端调用执行特定操作
- **`register_resources(mcp)`** 📚: 注册资源处理器，用于提供可读取的数据资源
- **`register_prompts(mcp)`** 💡: 注册提示模板，用于生成特定场景的提示内容
- **`get_name()`** 🏷️: 获取客户端名称（已提供默认实现）
#### 3. 🌟 实现最佳实践
<details>
<summary>⚠️ 错误处理</summary>
```python
async def your_tool(self, arguments: dict) -> list[types.TextContent]:
try:
result = await self._execute_logic(arguments)
return [types.TextContent(type="text", text=result)]
except Exception as e:
error_msg = f"执行失败: {str(e)}"
return [types.TextContent(type="text", text=error_msg)]
```
</details>
<details>
<summary>✅ 参数验证</summary>
```python
def _validate_arguments(self, arguments: dict, required_fields: list) -> None:
"""验证必需参数"""
missing_fields = [field for field in required_fields if field not in arguments]
if missing_fields:
raise ValueError(f"缺少必需参数: {', '.join(missing_fields)}")
```
</details>
<details>
<summary>📋 日志记录</summary>
```python
import logging
logger = logging.getLogger(__name__)
async def your_tool(self, arguments: dict) -> list[types.TextContent]:
logger.info(f"执行工具: {arguments}")
# ...implementation...
logger.info("工具执行完成")
```
</details>
## 🔐 安全注意事项
> ⚠️ **重要提醒**：
> - 🚫 不要在代码库中提交真实的密码、私钥等敏感信息
> - 🛡️ 建议使用环境变量或安全的配置管理工具
> - 🔄 定期更换 SSH 密码和 API 密钥
> - 🔒 确保私钥文件的权限设置正确
---
<div align="center">
## 📄 许可证
本项目采用 [MIT 许可证](LICENSE)。
## 🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进本项目！
[](https://github.com/peroperogames/pero-mcp-server/graphs/contributors)
## 💬 支持
如果您在使用过程中遇到问题，请通过 [GitHub Issues](https://github.com/peroperogames/pero-mcp-server/issues) 反馈。
---
*Made with ❤️ by peropero*
</div>