LLM tools: OpenAI and MCP

Added in version 1.2.5.

The gitcode_api.llm package bundles optional adapters so agents can call the same resource-oriented API as GitCode and AsyncGitCode, without duplicating endpoint logic.

Heavy dependencies (for example FastMCP) load lazily when you import symbols from gitcode_api.llm; only the symbols you use trigger their submodule imports.

Logical tool: gitcode_api_tool

All adapters expose one logical function tool named ``gitcode_api_tool``. Model-facing arguments follow the JSON Schema used by OpenAI-style function calling:

Parameter

Role

op_type (required)

Resource group on the client (same names as attributes on GitCode, for example repos, pulls, issues).

action

Method on that resource (for example get, list). When empty and combined with help, returns discovery text instead of a normal call.

params

Keyword arguments for the method as a JSON object; omitted or null is treated as {}.

help

When true, returns formatted help (available methods or a target signature) instead of performing a request where applicable.

Successful values are JSON-friendly (APIObject.to_dict(), base64-wrapped bytes, and similar). Failures are objects with "error": true and a "message" string; HTTP and configuration errors may include extra fields.

OpenAI Chat Completions tool

GitCodeOpenAITool ships with the core package (no MCP extra). It wraps GitCodeLLMTool with:

  • .tool / to_dict() — payload in OpenAI Chat Completions tools shape (type: function, name gitcode_api_tool, shared schema).

  • Callable invocation with (op_type, action, params=..., help=...) in sync mode, or async_mode=True for the async path.

from gitcode_api.llm import GitCodeOpenAITool

tool = GitCodeOpenAITool(owner="SushiNinja", repo="GitCode-API")
tools_payload = [tool.tool]

result = tool("repos", "get", params={})

async_tool = GitCodeOpenAITool(owner="SushiNinja", repo="GitCode-API", async_mode=True)
# await async_tool("pulls", "list", params={"state": "open", "per_page": 5})

You can pass the emitted tool definition straight into an OpenAI client and handle tool calls directly:

import json
from openai import OpenAI
from gitcode_api.llm import GitCodeOpenAITool

tools = {
    "gitcode_api_tool": GitCodeOpenAITool(owner="SushiNinja", repo="GitCode-API"),
}
client = OpenAI(
    api_key="your-openai-compatible-api-key",
    base_url="https://your-openai-compatible-base-url/v1",
)

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "List the last 5 commits."}],
    tools=[tools["gitcode_api_tool"].tool],
)

for tool_call in response.choices[0].message.tool_calls:
    selected_tool = tools[tool_call.function.name]
    print(f"Calling tool {tool_call.function.name}({tool_call.function.arguments}):")
    print("---result---")
    print(selected_tool(**json.loads(tool_call.function.arguments)))
    print("---result---")

Constructor arguments mirror the clients: client=, async_client=, api_key=, owner=, repo=, base_url=, timeout=, decrypt=. For dict-driven setups that reserve the name async, you may pass **{"async": True} instead of async_mode=True (but not both).

Shared tool instance

To reuse authentication or HTTP clients across several integrations, construct GitCodeLLMTool once and pass it as tool= into GitCodeMCP, create_mcp_server(), register_mcp_gitcode_api_tool(), or create_mcp_gitcode_api_tool().

from gitcode_api.llm._tool import GitCodeLLMTool

shared = GitCodeLLMTool(owner="SushiNinja", repo="GitCode-API")

The gitcode_api.llm._tool module is internal-facing but stable for this tool= sharing pattern (also described in the project README).

MCP (FastMCP)

Model Context Protocol integration uses FastMCP. Install the optional extra (Python 3.10+ is required because of the fastmcp dependency pin):

pip install 'gitcode-api[mcp]'

Public helpers (see module reference below):

  • create_mcp_server() — returns a FastMCP instance with gitcode_api_tool already registered; name=, tool=, and other keyword arguments are forwarded to FastMCP(...).

  • GitCodeMCP — constructs that server and registers the tool; unknown attributes are delegated to the underlying FastMCP object (for example transport helpers for your installed FastMCP version).

  • create_mcp_gitcode_api_tool() — standalone async callable used as the tool body for custom wiring.

  • register_mcp_gitcode_api_tool() — attaches that callable to an existing FastMCP-compatible server (mcp.tool(...) or mcp.add_tool(...) depending on the API).

from gitcode_api.llm import create_mcp_server

mcp = create_mcp_server(name="GitCode API", owner="SushiNinja", repo="GitCode-API")
# Start the server using FastMCP’s API for your version (stdio, HTTP, etc.).

The same server is exposed from the CLI as gitcode-api serve; see CLI.

Corporate TLS / custom httpx clients

If you need a custom CA or proxy settings, build GitCode / AsyncGitCode with http_client= / async_client= and pass those instances into GitCodeOpenAITool or MCP helpers via client= / async_client=, or pass a preconfigured GitCodeLLMTool via tool=, so tool calls reuse the same TLS stack as the rest of your app.

Further reading