# 向 Godot MCP 贡献代码

感谢您考虑为 Godot MCP 做出贡献！本文档概述了为该项目做出贡献的流程。

## 行为准则

参与本项目即表示您同意维护一个尊重和包容每一个人的环境。

## 我该如何贡献？

### 报告 Bug

- 检查该 Bug 是否已经在 Issues 部分报告过
- 如果有 Bug 报告模板，请使用它
- 提供重现 Bug 的详细步骤
- 包含任何相关的日志或截图
- 说明您的环境（操作系统、Godot 版本、Python 版本等）

### 建议改进

- 检查该改进建议是否已经在 Issues 部分提出过
- 如果有功能请求模板，请使用它
- 清楚地描述改进内容及其好处
- 考虑该改进是否符合项目的范围

### 提交 Pull Request

1. Fork 本仓库
2. 为您的功能或修复创建一个新分支 (`git checkout -b feature/amazing-feature`)
3. 进行更改
4. 运行测试以确保一切正常
5. 提交您的更改并附上清晰的提交信息
6. 推送到您的分支 (`git push origin feature/amazing-feature`)
7. 开启 Pull Request

## 开发流程

### 设置开发环境

1. 克隆仓库
2. 安装 [uv](https://docs.astral.sh/uv/) 包管理器
3. 同步依赖：
   ```bash
   uv sync
   ```
4. 在本地运行服务器：
   ```bash
   uv run python godot_mcp/server.py
   ```

### 项目结构

```
godot-mcp/
├── godot_mcp/         # 源代码
│   ├── scripts/       # GDScript 辅助脚本 (godot_operations.gd)
│   └── server.py      # 主要 MCP 服务器实现
├── tests/             # 测试文件
├── LICENSE            # MIT 许可证
├── README.md          # 文档
├── README.zh-CN.md    # 中文文档
├── CONTRIBUTING.md    # 贡献指南
└── pyproject.toml     # 项目配置
```

### 代码风格

- 遵循 Python 代码的 PEP 8 指南
- **类型提示 (Type Hinting)**：所有函数和变量必须完全包含类型提示
- **文档字符串 (Docstrings)**：所有函数和类必须包含标准的文档字符串
- 使用清晰且描述性强的变量名和函数名
- 优雅地处理错误并提供详细的错误信息

### 调试

调试 MCP 服务器：

1. 将 `DEBUG` 环境变量设置为 `true`
2. 使用 `mcp dev` 运行服务器进行交互式调试：
   ```bash
   uv run mcp dev godot_mcp/server.py
   ```
3. 检查日志以获取详细信息

### 添加新工具

向 MCP 服务器添加新工具时：

1. 在 `godot_mcp/server.py` 中使用 `@mcp.tool()` 装饰器定义工具
2. 添加适当的类型提示和文档字符串（这些用于生成工具 Schema）
3. 实现逻辑，必要时调用 Godot 操作
4. 在 README.md 中更新新工具的文档

#### 工具实现示例

```python
@mcp.tool()
async def my_new_tool(param1: str, param2: int = 10) -> str:
    """
    Description of what the tool does.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2
    """
    # implementation here
    server_instance.log_debug(f"Running my_new_tool with {param1}")
    
    if not validate(param1):
        raise ValueError("Invalid parameter")
        
    return f"Result: {param1} * {param2}"
```

### 跨平台兼容性

进行更改时，请确保它们在不同平台上都能工作：

- 使用 `pathlib` 或 `os.path` 处理文件路径，而不是硬编码字符串
- 尽可能在不同的操作系统上进行测试
- 考虑不同的 Godot 安装位置

## 测试

- 使用 pytest 运行测试：
  ```bash
  uv run pytest
  ```
- 为新功能在 `tests/` 目录中添加新测试
- 提交 Pull Request 前确保所有测试通过

## 文档

- 保持 README.md（以及 README.zh-CN.md）随新功能更新
- 记录所有工具及其参数
- 包含新功能的示例

## 有问题？

如果您对贡献有任何疑问，请随时开启 Issue 进行讨论。

感谢您的贡献！
