GitCode-API

gitcode-api 是由社区维护的 GitCode REST API Python SDK：提供同步与异步客户端、按资源组分类的调用方式，以及带类型注释的响应模型，让你在 Python 里调用 GitCode 时不必手写底层 HTTP。我们还提供 OpenAI 格式的工具、MCP 服务，以及 openJiuwen 格式的工具集成，便于智能体复用同一套 API。

项目定位

• 面向需要在 Python 中接入 GitCode 的开发者。
• 同步（GitCode）与异步（AsyncGitCode）两套接口形状一致，便于迁移或混用。
• 提供 REST API 无法直接达成的复杂功能：比如 Issue 与 PR 模版的获取。
• 通过 client.repos、client.pulls、client.users 等资源组挂载具体 API。
• 可在构造客户端时设置 owner、repo，作为仓库相关接口的默认上下文。
• 本仓库含 Sphinx 文档与 GitCode REST API 参考镜像。
• 提供面向 LLM 智能体的 MCP 服务、OpenAI 工具，以及 openJiuwen 工具。
• 提供可一键安装到常用 AI IDE（如 Cursor、VS Code）的 MCP 服务。
• 提供可直接安装至 Claude 桌面应用使用的 mcpb包，在 Release 页面下载。

安装

推荐从 PyPI 安装：

pip install -U gitcode-api

将 MCP 服务器安装到你常用的 AI IDE：

详细安装说明（包括安装到 Claude Code / Codex 等服务）见 install_mcp_server.md。

认证

可直接传入 api_key，或将访问令牌写入环境变量：

export GITCODE_ACCESS_TOKEN="your-token"

若令牌以密文形式保存，可在构造客户端时传入 decrypt，在发起请求前解密 api_key 或环境变量 GITCODE_ACCESS_TOKEN：

from gitcode_api import GitCode
from trusted_library import decrypt_token

client = GitCode(
    api_key="encrypted-token",
    decrypt=decrypt_token,
)

CLI

安装后可通过命令行调用 SDK，例如：

gitcode-api repos get --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API
python -m gitcode_api pulls list --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API --state open

已安装 gitcode-api[mcp]（Python 3.10+）时，可通过 stdio 启动内置的 FastMCP 服务：

gitcode-api serve --api-key "$GITCODE_ACCESS_TOKEN"

gitcode-api serve -h 可查看 --owner、--repo、--transport（stdio、http、sse）等选项。

子命令与同步客户端 GitCode 上各资源组的方法一一对应，形如 gitcode-api <resource> <method> ...。若某方法还支持额外参数，可多次使用 --set key=value，或使用 --set-json '{"key": "value"}' 传入。

当传入的参数包含转义字符时（比如换行符 \n），可使用 -e / --escape 指定要反转义的字符，例如 -e '\n\t'。

快速开始

同步客户端

from gitcode_api import GitCode

client = GitCode(
    owner="SushiNinja",
    repo="GitCode-API",
)

repo = client.repos.get()
branches = client.branches.list(per_page=5)

print(repo.full_name)
for branch in branches:
    print(branch.name)

异步客户端

import asyncio
from gitcode_api import AsyncGitCode

async def main() -> None:
    client = AsyncGitCode(owner="SushiNinja", repo="GitCode-API")
    pulls = await client.pulls.list(state="open", per_page=20)
    print(len(pulls))

asyncio.run(main())

使用 as_dict 将返回对象转为字典

接口返回值均为带有类型注释的 APIObject 子类。若需要序列化，或下游代码期望使用 dict 类型，可直接使用 as_dict 函数：传入单个模型得到 dict，传入列表（例如 client.pulls.list(...) 的返回值）则得到 list[dict]。语义上接近 dataclasses.asdict，但实际会调用各模型的 to_dict() 方法。需要与原始对象完全脱钩的深度拷贝时，请使用 deep_copy=True。

from gitcode_api import GitCode, as_dict

client = GitCode(owner="SushiNinja")
pulls = client.pulls.list_templates(repo="GitCode-API")
payload = as_dict(pulls)  # list[dict]

repo = client.repos.get(repo="GitCode-API")
meta = as_dict(repo)  # dict

上下文管理器

GitCode 与 AsyncGitCode（以及更底层的 SyncAPIClient / AsyncAPIClient）均可作为 with / async with 的上下文使用：离开代码块时会自动调用 close() 或 await close()，释放底层 httpx 客户端；若你传入了自定义 http_client，也会随 SDK 客户端一并关闭。close() 还会清空各资源组上 method_signature(...) 的 LRU 缓存见 资源组，避免 LRU 缓存在关闭后仍持有引用、影响垃圾回收。

from gitcode_api import GitCode

with GitCode(owner="SushiNinja", repo="GitCode-API") as client:
    repo = client.repos.get()
    print(repo.full_name)

import asyncio
from gitcode_api import AsyncGitCode

async def main() -> None:
    async with AsyncGitCode(owner="SushiNinja", repo="GitCode-API") as client:
        pulls = await client.pulls.list(state="open", per_page=20)
        print(len(pulls))

asyncio.run(main())

常见场景示例

创建 Pull Request：

from gitcode_api import GitCode

client = GitCode(owner="SushiNinja", repo="GitCode-API")

pull = client.pulls.create(
    title="Add feature",
    head="feature-branch",
    base="main",
    body="Implements the new flow.",
)
print(pull.number)

获取当前登录用户：

from gitcode_api import GitCode

client = GitCode()

user = client.users.me()
print(user.login)

搜索仓库：

from gitcode_api import GitCode

client = GitCode()

repos = client.search.repositories(q="sdk language:python", per_page=10)
for repo in repos:
    print(repo.full_name)

资源组

GitCode 与 AsyncGitCode 均暴露下列资源组：

• repos 与 contents
• branches 与 commits
• issues 与 pulls
• labels、milestones 与 members
• releases、tags 与 webhooks
• users、orgs、search 与 oauth

每个资源组（例如 client.pulls、client.repos）在共享基类上带有缓存属性 methods：值为该组对外可调用的方法名组成的 tuple。顺序由 SDK 根据方法名中下划线分段生成排序键决定，并非对完整方法名做字典序排列。不包含以下划线开头的名称，也不包含内省辅助方法 methods 与 method_signature。适合在交互环境或工具链中快速查看某组暴露了哪些接口。若需要单个方法的参数与返回类型，可调用 client.pulls.method_signature("list_issues")（基于 inspect.signature 的缓存字符串，注解中的 gitcode_api._models. 前缀会被去掉）。

LLM 工具、MCP 与 openJiuwen

gitcode_api.llm 模块对外提供一个统一的工具 gitcode_api_tool，自动将调用路由到对应的同步或异步 SDK 资源组。面向模型的参数与 OpenAI 风格函数工具的 JSON Schema 一致：

参数	作用
op_type	必填。客户端上的资源组名（与 GitCode 属性一致，如 repos、pulls、issues 等）。
action	该资源上的方法名（如 get、list）。在配合 help 时若为空，可返回方法发现说明文本。
params	传给该方法的关键字参数组成的 JSON 对象；省略或 null 视为 {}。
help	为 true 时，在适用场景下返回格式化的帮助信息（可用方法或目标方法签名），而非执行常规 API 请求。

工具负载为经 JSON 序列化后的字符串：成功时其内容类似普通对象（如 APIObject.to_dict()、对 bytes 做 base64 包装等）；失败时使用 "error": true、"message" 字段，HTTP 或配置错误在可用时附带额外字段。

OpenAI 工具（GitCodeOpenAITool）

除核心包外无需额外依赖。通过 .tool 或 to_dict() 生成 Chat Completions 风格的工具定义，再用上文参数以同步方式调用同一实例；需要 await 时启用异步模式。每次调用都会对负载执行 json.dumps，因此返回值始终为 str。默认关键字参数 indent=2 会美化 JSON；传入 indent=None 可得到紧凑的单行字符串。

from gitcode_api.llm import GitCodeOpenAITool

tool = GitCodeOpenAITool(owner="SushiNinja", repo="GitCode-API")
tools_payload = [tool.tool]  # 或单条使用 tool.to_dict()

# 默认：同步调用
result = tool("repos", "get", params={})

# 异步客户端 / 可 await 的封装
async_tool = GitCodeOpenAITool(owner="SushiNinja", repo="GitCode-API", async_mode=True)
# await async_tool("pulls", "list", params={"state": "open", "per_page": 5})

也可以直接把生成的工具定义传给 chat.completions.create(...)，并像 test.py 那样手动处理工具调用：

import json
import os
from typing import Dict, List
from openai import OpenAI
from gitcode_api.llm import GitCodeOpenAITool

MESSAGE_SEP = "\n" + "=" * 60 + "\n"
USER_QUERY = "List the repos owned by SushiNinja."
CONVERSATION: List[Dict[str, str]] = [dict(role="user", content=USER_QUERY)]

tools = {"gitcode_api_tool": GitCodeOpenAITool()}
client = OpenAI()

print("U:\n" + USER_QUERY + MESSAGE_SEP)
while True:
    response = (
        client.chat.completions.create(
            model="gpt-5.4-nano",
            messages=CONVERSATION,
            tools=[tools["gitcode_api_tool"].tool],
        )
        .choices[0]
        .message
    )
    CONVERSATION.append(response.to_dict())
    print("A:\n" + (response.content or ""))
    for tool_call in response.tool_calls or []:
        selected_tool = tools[tool_call.function.name]
        result = selected_tool(**json.loads(tool_call.function.arguments))
        CONVERSATION.append(dict(role="tool", tool_call_id=tool_call.id, content=result))
        print(f"<Calling tool {tool_call.function.name}({tool_call.function.arguments})>")
    print(MESSAGE_SEP)
    if not response.tool_calls:
        break

MCP 服务与 MCP 工具（FastMCP）

MCP 集成基于 FastMCP。请安装可选依赖组（因 fastmcp 约束，需 Python 3.10+）：

pip install 'gitcode-api[mcp]'

• create_mcp_server — 创建已注册 gitcode_api_tool 的 FastMCP 实例；可选 name、tool 以及其余关键字参数会原样传给 FastMCP(...)。
• GitCodeMCP — 薄封装：构造上述服务并注册工具；未定义的属性会委托给底层 FastMCP 对象（例如各版本 FastMCP 暴露的传输相关接口）。
• create_mcp_gitcode_api_tool — 返回独立的异步可调用对象，作为工具实现，供自定义挂载。
• register_mcp_gitcode_api_tool — 将上述可调用对象注册到已有的 FastMCP 兼容对象上（mcp.tool(...) 或 mcp.add_tool(...)）。

from gitcode_api.llm import create_mcp_server

mcp = create_mcp_server(name="GitCode API", owner="SushiNinja", repo="GitCode-API")
# 按你所用的 FastMCP 版本文档启动或导出服务（stdio、HTTP 等）。

等价地也可通过命令行 gitcode-api serve 启动同一套内置服务（见上文 CLI 小节）。

若要在多个工具间共享认证或客户端，可只构造一次 GitCodeLLMTool（from gitcode_api.llm._tool import GitCodeLLMTool），再以 tool 传入 GitCodeMCP、create_mcp_server、register_mcp_gitcode_api_tool 或 create_mcp_gitcode_api_tool。

openJiuwen（LocalFunction）

openJiuwen 是开放的智能体平台。另行安装 openjiuwen 包（Python 3.11+）后，可使用 create_openjiuwen_gitcode_api_tool 获得与 OpenAI 适配器使用相同 op_type / action / params / help 参数的 LocalFunction。调用方式为 仅异步（await jiuwen_tool.invoke({...})）。

pip install openjiuwen

from gitcode_api.llm import create_openjiuwen_gitcode_api_tool

jiuwen_tool = create_openjiuwen_gitcode_api_tool(owner="SushiNinja", repo="GitCode-API")
# jiuwen_tool.card — 名称、描述、input_params
# await jiuwen_tool.invoke({"op_type": "repos", "action": "get", "params": {}})

可用 name、description 覆盖默认工具卡。其余构造参数与 GitCode / AsyncGitCode 一致（client、async_client、api_key、owner、repo、base_url、timeout、decrypt）。

Claude Desktop（MCPB）： 每个已发布的 GitHub Release 会附带 gitcode-<version>.mcpb，可在 Claude Desktop 中作为扩展一键安装；说明见 Anthropic 文档 使用 MCPB 构建桌面扩展。在仓库根目录执行 make mcpb 可在本地打包（需已安装 @anthropic-ai/mcpb 并可在 PATH 中调用 mcpb）。

示例

可运行脚本位于 examples/：

• get_current_user.py
• get_repository_overview.py
• get_issue_templates.py
• get_pull_request_templates.py
• list_pull_requests.py
• async_list_branches.py

示例使用 python-dotenv 从 examples/.env 读取配置。

uv run python examples/get_current_user.py
uv run python examples/get_repository_overview.py
uv run python examples/get_issue_templates.py
uv run python examples/get_pull_request_templates.py
uv run python examples/list_pull_requests.py
uv run python examples/async_list_branches.py

环境变量说明见 examples/.env.example。

文档

• 文档总入口：docs/index.rst
• SDK 文档：docs/sdk/index.rst
• REST API 参考镜像：docs/rest_api/index.rst

在仓库根目录构建文档。make docs 会先清理旧的 docs/_build 与 docs/sdk/generated，再通过 uv 依次运行 Sphinx 的 html、epub、singlehtml 构建器；产物分别位于 docs/_build/html/、docs/_build/epub/（含 GitCodeAPI.epub）、docs/_build/singlehtml/：

make docs

在仓库根目录常用的其他 Makefile 目标（建议先执行 uv sync --all-groups，以便安装文档、测试、格式化等可选依赖组）：

• make docs-clean — 仅删除 docs/_build 与 docs/sdk/generated，不重新构建。
• make format — Ruff 修复、import 排序与代码格式化。
• make test — 将包安装到当前环境并运行 pytest。
• make docstring — 对 gitcode_api/ 运行 pydocstyle 检查。
• make binary — 使用 PyInstaller 打包单文件 CLI 到 dist/（需 binary 依赖组）。

常见问题

SSL 或企业网络报错（如「自签名证书」）

若在企业代理或私有 PKI 环境下访问 GitCode HTTPS 失败，可为 httpx 指定 verify 指向 CA 证书路径（思路类似 requests 使用的 REQUESTS_CA_BUNDLE）：

from gitcode_api import GitCode
from httpx import Client

with GitCode(
    owner="SushiNinja",
    repo="GitCode-API",
    http_client=Client(verify="path/to/my/certificate.crt"),
) as client:
    repo = client.repos.get()
    pulls = client.pulls.list(state="open", per_page=5)

0.1.16 版本：可通过设置环境变量 GITCODE_CA_BUNDLE 或 REQUESTS_CA_BUNDLE 指定默认CA 证书路径。

异步场景请对 AsyncGitCode 使用 httpx.AsyncClient(verify=...)。

OpenAI 工具（GitCodeOpenAITool）、MCP 相关接口与 create_openjiuwen_gitcode_api_tool 同样支持传入已配置好的 client / async_client（OpenAI 与 MCP 还可通过 tool 传入已设置上述客户端的 GitCodeLLMTool）。先用自定义 http_client 构造 GitCode / AsyncGitCode，再传入这些适配器，LLM 工具调用会沿用同一套 TLS 与证书配置，不必另做一套处理。

项目状态

本项目由社区维护，仍在持续演进。当前已覆盖大量 GitCode API；随着版本迭代，个别端点或行为仍可能被补充或调整。

贡献

欢迎提交 issue、改进文档、补充测试、扩展 API 封装或直接发起 pull request。若你在实际使用中发现缺失接口或不顺手的设计，也欢迎反馈与贡献。