cann-gitcode-mcp 0.2.0__tar.gz → 0.3.0__tar.gz

cann_gitcode_mcp-0.3.0/AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md — cann-gitcode-mcp
+
+## Project Overview
+
+`cann-gitcode-mcp` is an MCP server that exposes GitCode REST API (v5, base `https://gitcode.com/api/v5`) as MCP tools for CANN developers. Package: `cann-gitcode-mcp`; module: `cann_gitcode_mcp`.
+
+## Quick Reference
+
+```bash
+uv pip install -e ".[dev]"   # Install (or: pip install -e ".[dev]")
+pytest -v                     # Run tests
+python -m cann_gitcode_mcp    # Start MCP server (stdio)
+```
+
+| Env Variable | Required | Description |
+|---|---|---|
+| `GITCODE_API_TOKEN` | Yes | Personal access token from GitCode |
+| `GITCODE_API_BASE_URL` | No | Override API base (default: `https://gitcode.com/api/v5`) |
+
+## Architecture
+
+```
+src/cann_gitcode_mcp/
+├── __init__.py          # Package metadata
+├── __main__.py          # python -m entry → server.main()
+├── server.py            # FastMCP instance; wires all tool modules
+├── client.py            # GitCodeClient (async httpx wrapper)
+└── tools/
+    ├── __init__.py
+    ├── pull_request.py  # 7 PR tools
+    └── pipeline.py      # 2 pipeline tools (trigger + summary)
+```
+
+- **`server.py`** — creates `FastMCP("gitcode")`, calls every `register_*_tools(mcp)`. Single wiring point.
+- **`client.py`** — `GitCodeClient` reads `GITCODE_API_TOKEN` from env, provides async `get/post/patch/put/delete`. Raises `ValueError` if token unset, `RuntimeError` on non-2xx.
+- **`tools/`** — each file owns one domain. Tools registered via `@mcp.tool()` inside `register_*_tools(mcp)`.
+
+## Code Rules
+
+1. **Python 3.11+** — `from __future__ import annotations` at top of every file.
+2. **Async** — all tool functions must be `async def`.
+3. **Type hints** — all parameters and return types annotated.
+4. **Return `str`** — `json.dumps(data, ensure_ascii=False)`, no `indent`.
+5. **Docstrings** — first line = MCP tool description; `Args:` for params.
+6. **Registration** — tools via `@mcp.tool()` inside `register_*_tools(mcp)`, never at module import time.
+7. **No bare exceptions** — let errors propagate; MCP framework surfaces them.
+8. **No global state beyond `_client`** — the singleton is reset between tests via `patch`.
+
+## Adding a New Tool
+
+### 1. Create `src/cann_gitcode_mcp/tools/<domain>.py`
+
+```python
+from __future__ import annotations
+import json
+from mcp.server.fastmcp import FastMCP
+from cann_gitcode_mcp.client import GitCodeClient
+
+_client: GitCodeClient | None = None
+
+def _get_client() -> GitCodeClient:
+    global _client
+    if _client is None:
+        _client = GitCodeClient()
+    return _client
+
+def register_<domain>_tools(mcp: FastMCP) -> None:
+
+    @mcp.tool()
+    async def get_thing(owner: str, repo: str, number: int) -> str:
+        """One-line description for MCP.
+
+        Args:
+            owner: Repository namespace
+            repo: Repository name
+            number: Item number
+        """
+        client = _get_client()
+        result = await client.get(f"/repos/{owner}/{repo}/things/{number}")
+        return json.dumps(result, ensure_ascii=False)
+```
+
+### 2. Register in `server.py`
+
+```python
+from cann_gitcode_mcp.tools.<domain> import register_<domain>_tools
+register_<domain>_tools(mcp)
+```
+
+### 3. Add tests in `tests/test_<domain>.py`
+
+```python
+import pytest
+from unittest.mock import AsyncMock, patch
+from mcp.server.fastmcp import FastMCP
+
+@pytest.fixture
+def mcp_server():
+    server = FastMCP("test")
+    with patch("cann_gitcode_mcp.tools.<domain>._client", None), \
+         patch.dict("os.environ", {"GITCODE_API_TOKEN": "test-token"}):
+        register_<domain>_tools(server)
+        yield server
+
+async def test_get_thing(mcp_server):
+    tool_fn = mcp_server._tool_manager._tools["get_thing"].fn
+    with patch("cann_gitcode_mcp.tools.<domain>.GitCodeClient.get",
+               new_callable=AsyncMock, return_value={"id": 1}):
+        result = await tool_fn(owner="org", repo="repo", number=1)
+    assert '"id": 1' in result
+```
+
+### 4. Verify
+
+```bash
+pytest tests/ -v  # All tests must pass before committing
+```
+
+## Token Budget Rules
+
+MCP tool tokens directly squeeze LLM context. Rules split into **input side** (tool definitions, fixed cost per turn) and **output side** (tool responses, variable cost per call).
+
+### Input Side — Tool Definitions (Fixed Cost)
+
+| # | Rule | Practice | Anti-pattern |
+|---|---|---|---|
+| I1 | 合并同域工具 | 相关操作合并为一个工具 + `action` 参数路由 | 一个 API endpoint = 一个 tool |
+| I2 | 描述只写决策信息 | 一行说"做什么"，`Args:` 只写参数含义 | 写示例、教程、实现细节、重复 schema 约束 |
+| I3 | enum 优先于 oneOf | `Literal["a","b"]` 生成 `enum` | `oneOf` 每个值一个 object，2-4x 膨胀 |
+| I4 | 预算守护 | `test_tool_definition_budget.py` 断言工具 ≤ 4、定义 ≤ 1300 tokens | 加工具不跑预算测试 |
+| I5 | 描述中不重复 schema | type/default/min/max 已在 JSON Schema，不再重复 | `"page: Page number (integer, minimum 1, default 1)"` |
+
+### Output Side — Tool Responses (Variable Cost)
+
+| # | Rule | Practice | Anti-pattern |
+|---|---|---|---|
+| O1 | 字段裁剪 | 只返回决策字段，用 `_slim_*`。丢弃 `_links`, `permissions`, `avatar_url` | 透传原始 API 响应（70-90% 冗余） |
+| O2 | 紧凑 JSON | `json.dumps(data, ensure_ascii=False)` 不加缩进 | `indent=2` 增加 30-40% token |
+| O3 | 摘要/详情分级 | `detail="summary"\|"full"` 参数；列表默认 key fields | 列表接口返回完整 body |
+| O4 | 大内容截断 | diff/日志设上限 `_MAX_DIFF_LINES`，超出截断 | 无限制返回大 diff/日志 |
+| O5 | 失败详细 / 成功折叠 | 失败项保留名称+状态+日志链接；成功项折叠为计数 | 成功失败全量输出 |
+| O6 | 写操作返回确认 | create/merge/comment 只返回 id + url | 返回完整创建对象 |
+| O7 | 公共前缀提取 | 多 URL 共享前缀时提取 `base_url` + 相对路径 | 每条记录完整 URL |
+| O8 | structuredContent 不双送 | `content` 和 `structuredContent` 只送一份 | 两者相同但都发送 |
+
+### Test Guards
+
+| Test | Responsibility |
+|---|---|
+| `test_tool_definition_budget.py` | 工具数量和定义 token 总量不超预算 |
+| `test_token_budget.py` | 每个工具响应 token ≤ 预算 |
+| `TestTokenReductionReport` | raw vs slim token 对比（信息性） |
+
+Token approximation: `len(text) // 4` (conservative for mixed CJK/English).
+
+### Current Baseline (2026-03-31)
+
+| Metric | Value |
+|---|---|
+| Tool count | 4 (2 PR + 2 pipeline) |
+| Definition tokens | ~1263 (budget: 1300) |
+| Max response budget | 600 tokens (`get_pr_pipeline_summary`) |
+| Response trimming | 87-95% vs raw API |
+
+### Scaling (When Tools > 8)
+
+Not needed at 4 tools, but plan ahead:
+
+- **Toolset filtering**: `--toolsets` flag, users enable only needed groups
+- **Lazy loading**: expose name + one-line summary, load full schema on demand (91% input savings)
+- **JSON `$ref`**: shared params defined once via `$ref`
+- **Code Mode**: sandbox replaces N tools (98%+ savings, per Anthropic/Cloudflare)
+
+## GitCode API Reference
+
+- Base URL: `https://gitcode.com/api/v5`
+- Auth: `Authorization: Bearer <token>`
+- PR endpoints: `/repos/{owner}/{repo}/pulls[/{number}[/merge|comments|files]]`
+- Pipeline data: extracted from cann-robot PR comments (no dedicated API); see `docs/pipeline-tools-research.md`

cann_gitcode_mcp-0.3.0/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+<!-- 本项目开发指南统一维护在 AGENTS.md，避免重复 -->
+
+See [AGENTS.md](AGENTS.md) for all project guidelines.

{cann_gitcode_mcp-0.2.0 → cann_gitcode_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cann-gitcode-mcp
-Version: 0.2.0
+Version: 0.3.0
 Summary: CANN GitCode MCP Server - GitCode platform tools for CANN developers
 Project-URL: Homepage, https://gitcode.com/shengnan666/cann-gitcode-mcp
 Project-URL: Repository, https://gitcode.com/shengnan666/cann-gitcode-mcp
@@ -45,12 +45,33 @@ pip install cann-gitcode-mcp
 
 ### 2. 配置 Claude Code
 
-先在 [GitCode 用户设置](https://gitcode.com/setting/token-classic) 中生成个人访问令牌，然后在 Claude Code 的 MCP 配置文件（`~/.claude/settings.json` 或项目级 `.mcp.json`）中添加：
+先在 [GitCode 用户设置](https://gitcode.com/setting/token-classic) 中生成个人访问令牌，然后按需选择配置范围：
+
+**方式一：当前用户范围（对本用户的所有项目生效）**
+
+编辑 `~/.claude.json`，在顶层添加 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "cann-gitcode": {
+      "command": "cann-gitcode-mcp",
+      "env": {
+        "GITCODE_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**方式二：仅当前工程生效（可提交到版本库，团队共享）**
+
+在项目根目录创建或编辑 `.mcp.json`：
 
 ```json
 {
   "mcpServers": {
-    "gitcode": {
+    "cann-gitcode": {
       "command": "cann-gitcode-mcp",
       "env": {
         "GITCODE_API_TOKEN": "your_token_here"
@@ -60,6 +81,8 @@ pip install cann-gitcode-mcp
 }
 ```
 
+> **注意**：`.mcp.json` 若提交到版本库，其他协作者也会加载该 MCP 配置，但每人需在自己机器上安装 `cann-gitcode-mcp` 并填写自己的 Token。如果 Token 因人而异，可将 `.mcp.json` 加入 `.gitignore`，或仅配置不含 Token 的部分，通过其他方式注入环境变量。
+
 重启 Claude Code 即可使用。
 
 > **环境变量说明**：Token 通过 MCP 配置的 `env` 字段传入即可，无需手动 `export`。如需覆盖 API 地址，可额外设置 `GITCODE_API_BASE_URL`（默认 `https://gitcode.com/api/v5`）。
@@ -82,8 +105,11 @@ pip install cann-gitcode-mcp
 
 | 工具名 | 说明 |
 |--------|------|
+| `trigger_pr_pipeline` | 向 PR 发送 `compile` 评论以触发 CI/CD 流水线 |
 | `get_pr_pipeline_summary` | 获取 PR 的 CI/CD 流水线摘要（解析 cann-robot 评论） |
 
+`trigger_pr_pipeline` 通过在 PR 下发表 `compile` 评论来触发 cann-robot 启动流水线。**注意**：重复触发会中止当前运行的流水线并重新启动，请勿多次调用。
+
 `get_pr_pipeline_summary` 从 PR 评论中解析 cann-robot 发布的流水线结果，返回每个任务的名称、状态（SUCCESS/FAILED/ABORTED）、日志链接、构建产物下载链接，以及整体 CI 结论。无需 openLiBing token，仅使用 GitCode API。
 
 ## 路线图

{cann_gitcode_mcp-0.2.0 → cann_gitcode_mcp-0.3.0}/README.md

@@ -16,12 +16,33 @@ pip install cann-gitcode-mcp
 
 ### 2. 配置 Claude Code
 
-先在 [GitCode 用户设置](https://gitcode.com/setting/token-classic) 中生成个人访问令牌，然后在 Claude Code 的 MCP 配置文件（`~/.claude/settings.json` 或项目级 `.mcp.json`）中添加：
+先在 [GitCode 用户设置](https://gitcode.com/setting/token-classic) 中生成个人访问令牌，然后按需选择配置范围：
+
+**方式一：当前用户范围（对本用户的所有项目生效）**
+
+编辑 `~/.claude.json`，在顶层添加 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "cann-gitcode": {
+      "command": "cann-gitcode-mcp",
+      "env": {
+        "GITCODE_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**方式二：仅当前工程生效（可提交到版本库，团队共享）**
+
+在项目根目录创建或编辑 `.mcp.json`：
 
 ```json
 {
   "mcpServers": {
-    "gitcode": {
+    "cann-gitcode": {
       "command": "cann-gitcode-mcp",
       "env": {
         "GITCODE_API_TOKEN": "your_token_here"
@@ -31,6 +52,8 @@ pip install cann-gitcode-mcp
 }
 ```
 
+> **注意**：`.mcp.json` 若提交到版本库，其他协作者也会加载该 MCP 配置，但每人需在自己机器上安装 `cann-gitcode-mcp` 并填写自己的 Token。如果 Token 因人而异，可将 `.mcp.json` 加入 `.gitignore`，或仅配置不含 Token 的部分，通过其他方式注入环境变量。
+
 重启 Claude Code 即可使用。
 
 > **环境变量说明**：Token 通过 MCP 配置的 `env` 字段传入即可，无需手动 `export`。如需覆盖 API 地址，可额外设置 `GITCODE_API_BASE_URL`（默认 `https://gitcode.com/api/v5`）。
@@ -53,8 +76,11 @@ pip install cann-gitcode-mcp
 
 | 工具名 | 说明 |
 |--------|------|
+| `trigger_pr_pipeline` | 向 PR 发送 `compile` 评论以触发 CI/CD 流水线 |
 | `get_pr_pipeline_summary` | 获取 PR 的 CI/CD 流水线摘要（解析 cann-robot 评论） |
 
+`trigger_pr_pipeline` 通过在 PR 下发表 `compile` 评论来触发 cann-robot 启动流水线。**注意**：重复触发会中止当前运行的流水线并重新启动，请勿多次调用。
+
 `get_pr_pipeline_summary` 从 PR 评论中解析 cann-robot 发布的流水线结果，返回每个任务的名称、状态（SUCCESS/FAILED/ABORTED）、日志链接、构建产物下载链接，以及整体 CI 结论。无需 openLiBing token，仅使用 GitCode API。
 
 ## 路线图

cann_gitcode_mcp-0.3.0/docs/repo-application.md

@@ -0,0 +1,102 @@
+# cann-gitcode-mcp 建仓申请材料
+
+## 仓库名称
+
+`cann-gitcode-mcp`
+
+## 一、仓库用途
+
+为 CANN 开发者提供 GitCode 平台的 MCP（Model Context Protocol）工具服务。将 GitCode REST API 封装为标准 MCP 工具，使 Claude Code 等 AI 编程助手能够在对话中直接执行 Pull Request 管理、CI/CD 流水线触发与状态查询等 GitCode 平台操作，消除开发者在 AI 助手与 GitCode Web 界面之间的频繁切换。
+
+## 二、建仓目的
+
+CANN 社区的代码托管在 GitCode 平台，而当前主流 AI 编程助手（如 Claude Code）仅原生支持 GitHub。GitCode 官方尚未发布 MCP 服务，而 CANN 社区的 AI 辅助研发需求已经迫切，我们选择先行建设而非被动等待。
+
+本项目的定位**不是简单的 GitCode API 封装**，而是在 GitCode 基础能力之上，结合 CANN 社区特有的研发规范构建上层工具。项目包含两个层次的能力：
+
+- **GitCode 平台能力**：PR 全生命周期管理（创建、查询、合并、评论、变更文件查看），为 AI 助手提供基础的平台操作能力。
+- **CANN 研发规范工具**：基于 CANN 社区的 CI/CD 规范，实现 cann-robot 流水线触发、构建结果解析（任务状态、日志链接、构建产物），在对话中完成"提交→触发→查看结果"的闭环。这些工具与 CANN 构建体系深度绑定，是本仓的核心差异化价值。
+
+> **与 GitCode 官方 MCP 的关系**：若 GitCode 官方未来发布 MCP 服务，本项目中 GitCode 平台能力部分可平滑切换至官方实现或将已有实现贡献给官方，CANN 研发规范工具不受影响，继续独立演进。
+
+## 三、仓库价值
+
+1. **降低工具切换成本**：开发者在 AI 助手中即可完成 GitCode 平台操作，减少上下文切换，提升研发效率。
+2. **补齐 AI 辅助研发短板**：GitCode 官方尚未提供 MCP 服务，本项目先行填补这一空白，使 CANN 社区不必等待即可用上 AI 辅助研发能力。
+3. **标准化协议，可扩展性强**：基于 MCP 开放协议实现，不绑定特定 AI 客户端，任何支持 MCP 的工具均可接入。
+4. **已发布可用**：当前版本（0.2.0）已发布至 PyPI，提供 9 个生产可用的工具函数，覆盖 PR 管理和流水线查询两大核心场景。
+
+## 四、未来演进
+
+| 阶段 | 内容 | 说明 |
+|------|------|------|
+| 近期 | 多 Agent 客户端支持 | 适配 OpenCode、Codex 等更多 MCP 客户端，扩大工具覆盖面 |
+| 中期 | 流水线详情（L2） | 对接 openLiBing API，获取 stage/job/step 级别的详细信息和错误定位 |
+| 长期 | 更多 CANN 工具 | 根据社区研发规范扩展更多 CANN 专属工具, 例如触发 RDV 等 |
+| 持续 | 与 GitCode 官方协同 | 官方发布 MCP 后，平台能力部分可切换至官方或贡献上游，CANN 工具独立演进 |
+
+## 五、技术栈
+
+| 类别 | 技术选型 | 说明 |
+|------|----------|------|
+| 语言 | Python 3.11+ | 使用现代类型标注，全异步实现 |
+| 核心协议 | MCP (Model Context Protocol) | Anthropic 主导的开放协议，`mcp>=1.0` SDK |
+| HTTP 客户端 | httpx | 异步 HTTP 库，封装 GitCode REST API v5 调用 |
+| 构建工具 | Hatchling | PEP 517 标准构建后端 |
+| 测试框架 | pytest + pytest-asyncio | 异步测试，mock 网络层，无外部依赖 |
+| 分发渠道 | PyPI | `pip install cann-gitcode-mcp` 即可安装 |
+| 许可证 | Apache License 2.0 | 与 CANN 社区许可证保持一致 |
+
+## 附录：MCP 在 AI Agent 体系中的位置
+
+> **一句话定位**：Agent 是大脑，Skill 是内功，MCP 是双手 —— Agent 负责理解与决策，Skill 定义做事的方法论，MCP 让 Agent 能操作外部世界。
+
+```
+                        ┌───────────────────────────────┐
+                        │         开发者 (用户)          │
+                        └───────────────┬───────────────┘
+                                        │ 自然语言对话
+                                        ▼
+                ┌───────────────────────────────────────────────────┐
+                │               AI Agent (Claude Code)              │
+                │                                                   │
+                │    理解意图 → 规划步骤 → 调度能力 → 交付结果       │
+                │                                                   │
+                │    ┌─────────────┐       ┌──────────────────────┐ │
+                │    │   Skills    │       │    MCP Clients       │ │
+                │    │  (内置技能) │       │   (工具连接器)       │ │
+                │    │             │       │                      │ │
+                │    │ · 代码编辑  │       │  MCP 协议 (JSON-RPC) │ │
+                │    │ · 调试推理  │       │     │    │    │      │ │
+                │    │ · 测试驱动  │       │     ▼    ▼    ▼      │ │
+                │    │ · Git 操作  │       │    ┌──┐┌──┐┌──┐     │ │
+                │    │ · ...       │       │    │S1││S2││S3│     │ │
+                │    └─────────────┘       │    └──┘└──┘└──┘     │ │
+                └──────────────────────────│─────────────────────┘ │
+                                           └───┬────┬────┬─────────┘
+                                               │    │    │
+                                ┌──────────────┘    │    └──────────────┐
+                                ▼                   ▼                   ▼
+                 ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+                 │  MCP Server S1  │ │  MCP Server S2  │ │  MCP Server S3  │
+                 │ cann-gitcode-mcp│ │   (其他 MCP)    │ │   (其他 MCP)    │
+                 │                 │ │                 │ │                 │
+                 │ · create_pr     │ │ · 数据库查询    │ │ · 文档检索      │
+                 │ · merge_pr      │ │ · 消息通知      │ │ · 监控告警      │
+                 │ · trigger_ci    │ │ · ...           │ │ · ...           │
+                 │ · ...           │ │                 │ │                 │
+                 └────────┬────────┘ └────────┬────────┘ └────────┬────────┘
+                          │                   │                   │
+                          ▼                   ▼                   ▼
+                 ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+                 │  GitCode API    │ │   外部服务 B    │ │   外部服务 C    │
+                 └─────────────────┘ └─────────────────┘ └─────────────────┘
+```
+
+**三者关系**：
+
+| 概念 | 类比 | 职责边界 |
+|------|------|----------|
+| **Agent** | 大脑 | 理解用户意图，规划任务步骤，决定调用哪些能力 |
+| **Skill** | 内功 | Agent 内置的方法论与工作流（如 TDD、调试策略），不涉及外部系统 |
+| **MCP** | 双手 | 标准化的外部工具协议，让 Agent 能操作任意平台，本项目即通过 MCP 让 Agent 操作 GitCode |

cann_gitcode_mcp-0.3.0/docs/token-antipatterns-todo.md

@@ -0,0 +1,162 @@
+# Token 反模式 TODO
+
+审计日期：2026-03-31
+对照规则：AGENTS.md "Token Budget Rules"
+
+## 反模式清单
+
+### AP-1: `pull_request_write(create)` 透传原始 API 响应 [违反 O1, O6]
+
+**文件**: `src/cann_gitcode_mcp/tools/pull_request.py:281`
+
+```python
+result = await client.post(f"/repos/{owner}/{repo}/pulls", json=payload)
+return _text_result(result)  # ← 原始 API 响应，未裁剪
+```
+
+**问题**: create 返回完整 PR 对象（含 `_links`, `permissions`, `mergeable_state` 等 30+ 字段），写操作应只返回确认信息。
+
+**修复**: 返回 `_slim_pr(result)` 或更精简的确认：`{"number": N, "html_url": "...", "action": "created"}`。
+
+**预期节省**: ~200-400 tokens/次
+
+**优先级**: P1
+
+---
+
+### AP-2: `pull_request_write(merge)` 透传原始 API 响应 [违反 O6]
+
+**文件**: `src/cann_gitcode_mcp/tools/pull_request.py:292`
+
+```python
+result = await client.put(..., json=payload)
+return _text_result(result)  # ← 原始 merge 响应
+```
+
+**问题**: merge 响应可能包含冗余字段。写操作应返回精简确认。
+
+**修复**: 只返回 `{"pr": "owner/repo#N", "action": "merged", "merge_method": "..."}`。
+
+**预期节省**: ~50-100 tokens/次
+
+**优先级**: P2
+
+---
+
+### AP-3: `trigger_pr_pipeline` 响应中 message 冗余 [违反 I2 精神]
+
+**文件**: `src/cann_gitcode_mcp/tools/pipeline.py:197-201`
+
+```python
+return _text_result({
+    "pr": f"{owner}/{repo}#{pr_number}",
+    "action": "pipeline_triggered",
+    "message": "Posted 'compile' comment. Pipeline will start shortly. "
+               "Use get_pr_pipeline_summary to check status.",
+    "comment_id": result.get("id"),
+})
+```
+
+**问题**: `message` 字段是给人看的指引文本，LLM 不需要被告知 "use tool X to do Y"。LLM 自己知道工具链。
+
+**修复**: 删除 `message` 字段，或缩短为 `"status": "triggered"`。
+
+**预期节省**: ~25 tokens/次
+
+**优先级**: P3
+
+---
+
+### AP-4: CLAUDE.md 示例代码使用 `indent=2` [违反 O2]
+
+**文件**: `CLAUDE.md:62`（已修复）
+
+**问题**: 示例代码 `json.dumps(result, indent=2, ...)` 会误导新工具开发者加缩进。
+
+**状态**: ✅ 已修复
+
+---
+
+### AP-5: AGENTS.md "Important Constraints" 也写了 `indent=2` [违反 O2]
+
+**文件**: `AGENTS.md:126`（已修复）
+
+**状态**: ✅ 已修复
+
+---
+
+### AP-6: `get_pr_pipeline_summary` 无结果时返回冗余 message [违反 O6 精神]
+
+**文件**: `src/cann_gitcode_mcp/tools/pipeline.py:246-249`
+
+```python
+return _text_result({
+    **base_result,
+    "pipeline_found": False,
+    "message": "No pipeline comments found from cann-robot",
+})
+```
+
+**问题**: `pipeline_found: False` 已经表达了含义，`message` 冗余。
+
+**修复**: 删除 `message` 字段。
+
+**预期节省**: ~15 tokens/次
+
+**优先级**: P3
+
+---
+
+### AP-7: `pull_request_read(files)` 不支持 `detail="summary"` [违反 O3]
+
+**文件**: `src/cann_gitcode_mcp/tools/pull_request.py:217-218`
+
+**问题**: files action 忽略 `detail` 参数。summary 模式可以只返回 filename + status（不含 diff），显著减少 token。
+
+**修复**: `detail="summary"` 时只返回 `{"filename": ..., "status": ..., "additions": N, "deletions": N}`，不含 diff。
+
+**预期节省**: 50-80% per file（diff 是大头）
+
+**优先级**: P2
+
+---
+
+### AP-8: `pull_request_read(comments)` 不支持 `detail="summary"` [违反 O3]
+
+**文件**: `src/cann_gitcode_mcp/tools/pull_request.py:220-228`
+
+**问题**: comments action 忽略 `detail` 参数。summary 模式可以只返回 user + created_at（不含 body），用于快速浏览。
+
+**修复**: `detail="summary"` 时只返回 `{"id": ..., "user": ..., "created_at": ...}`。
+
+**预期节省**: 40-60% per comment（body 通常最长）
+
+**优先级**: P3
+
+---
+
+### AP-9: 缺少 `pull_request_write(create)` 的 token budget 测试 [违反测试要求]
+
+**文件**: `tests/test_token_budget.py`
+
+**问题**: BUDGETS 中没有 `pull_request_write:create` 的预算定义，也没有对应测试。create 返回原始 API 响应（AP-1），修复后需要加测试守护。
+
+**修复**: 添加 fixture + budget + 测试。
+
+**优先级**: P1（跟 AP-1 一起修复）
+
+---
+
+## 优先级总结
+
+| 优先级 | 编号 | 描述 | 预期节省 |
+|--------|------|------|----------|
+| **P1** | AP-1 | create PR 透传原始响应 | ~200-400 tok |
+| **P1** | AP-9 | create PR 缺 token budget 测试 | 守护 |
+| **P2** | AP-2 | merge PR 透传原始响应 | ~50-100 tok |
+| **P2** | AP-7 | files 不支持 summary 模式 | 50-80%/file |
+| **P3** | AP-3 | trigger_pipeline 冗余 message | ~25 tok |
+| **P3** | AP-6 | pipeline 无结果冗余 message | ~15 tok |
+| **P3** | AP-8 | comments 不支持 summary 模式 | 40-60%/comment |
+| ✅ | AP-4 | CLAUDE.md indent=2 示例 | 已修复 |
+| ✅ | AP-5 | AGENTS.md indent=2 约束 | 已修复 |

{cann_gitcode_mcp-0.2.0 → cann_gitcode_mcp-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cann-gitcode-mcp"
-version = "0.2.0"
+dynamic = ["version"]
 description = "CANN GitCode MCP Server - GitCode platform tools for CANN developers"
 readme = "README.md"
 license = "Apache-2.0"
@@ -44,6 +44,10 @@ cann-gitcode-mcp = "cann_gitcode_mcp.server:main"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+source = "code"
+path = "src/cann_gitcode_mcp/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/cann_gitcode_mcp"]
 

{cann_gitcode_mcp-0.2.0 → cann_gitcode_mcp-0.3.0}/src/cann_gitcode_mcp/__init__.py

@@ -1,3 +1,3 @@
 """CANN GitCode MCP Server - GitCode platform tools for CANN developers."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"