LLM tools: OpenAI and MCP ========================= .. versionadded:: 1.2.5 The ``gitcode_api.llm`` package bundles optional adapters so agents can call the same resource-oriented API as :class:`~gitcode_api.GitCode` and :class:`~gitcode_api.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: .. list-table:: :widths: 20 80 :header-rows: 1 * - Parameter - Role * - ``op_type`` (required) - Resource group on the client (same names as attributes on :class:`~gitcode_api.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 ---------------------------- :class:`~gitcode_api.llm.openai.GitCodeOpenAITool` ships with the **core** package (no MCP extra). It wraps :class:`~gitcode_api.llm._tool.GitCodeLLMTool` with: * ``.tool`` / :meth:`~gitcode_api.llm.openai.GitCodeOpenAITool.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. .. code-block:: python 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: .. code-block:: python 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 :class:`~gitcode_api.llm._tool.GitCodeLLMTool` once and pass it as ``tool=`` into :class:`~gitcode_api.llm.mcp.GitCodeMCP`, :func:`~gitcode_api.llm.mcp.create_mcp_server`, :func:`~gitcode_api.llm.mcp.register_mcp_gitcode_api_tool`, or :func:`~gitcode_api.llm.mcp.create_mcp_gitcode_api_tool`. .. code-block:: python 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): .. code-block:: bash pip install 'gitcode-api[mcp]' Public helpers (see module reference below): * :func:`~gitcode_api.llm.mcp.create_mcp_server` — returns a ``FastMCP`` instance with ``gitcode_api_tool`` already registered; ``name=``, ``tool=``, and other keyword arguments are forwarded to ``FastMCP(...)``. * :class:`~gitcode_api.llm.mcp.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). * :func:`~gitcode_api.llm.mcp.create_mcp_gitcode_api_tool` — standalone async callable used as the tool body for custom wiring. * :func:`~gitcode_api.llm.mcp.register_mcp_gitcode_api_tool` — attaches that callable to an existing FastMCP-compatible server (``mcp.tool(...)`` or ``mcp.add_tool(...)`` depending on the API). .. code-block:: python 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 :doc:`cli`. Corporate TLS / custom ``httpx`` clients ---------------------------------------- If you need a custom CA or proxy settings, build :class:`~gitcode_api.GitCode` / :class:`~gitcode_api.AsyncGitCode` with ``http_client=`` / ``async_client=`` and pass those instances into ``GitCodeOpenAITool`` or MCP helpers via ``client=`` / ``async_client=``, or pass a preconfigured :class:`~gitcode_api.llm._tool.GitCodeLLMTool` via ``tool=``, so tool calls reuse the same TLS stack as the rest of your app. Further reading --------------- * :doc:`index` — install, authentication, and client lifecycle. * :doc:`reference` — autodoc for ``gitcode_api.llm`` and submodules.