Skip to main content

gopher-mcp-python Python SDK

Python SDK for gopher-mcp-python, providing AI agent orchestration with native C++ performance through ctypes FFI bindings.

Features

  • Python 3.8+ compatibility
  • pip/setuptools build system
  • ctypes FFI bindings to native library
  • GopherAgent class with builder pattern configuration
  • Context manager support for automatic resource cleanup
  • Typed errors (AgentError, ApiKeyError, ConnectionError, TimeoutError)
  • Comprehensive test suite with pytest

Requirements

  • Python 3.8 or higher
  • venv and pip for PyPI installation, examples, and development workflows
  • Native gopher-mcp-python library (built from source)
  • On Linux, system OpenSSL runtime libraries (libssl / libcrypto) from your distribution. Native wheels do not bundle OpenSSL, so OS security updates remain effective.

On Debian/Ubuntu, install the Python venv and pip packages before using the PyPI install path, running examples, or setting up development dependencies:

sudo apt-get install python3 python3-venv python3-pip

Installation

From Source

  1. Clone the repository:
git clone https://github.com/GopherSecurity/gopher-mcp-python.git
cd gopher-mcp-python
  1. Build the native library:
./build.sh
  1. Install the Python package:
python3 -m pip install -e .

Quick Start

Using API Key

from gopher_mcp_python import GopherAgent, GopherAgentConfig

# Create configuration with API key
config = (GopherAgentConfig.builder()
    .provider("AnthropicProvider")
    .model("claude-3-haiku-20240307")
    .api_key("your-api-key")
    .build())

# Create and use agent with context manager
with GopherAgent.create(config) as agent:
    response = agent.run("What time is it in Tokyo?")
    print(response)

Using JSON Server Configuration

from gopher_mcp_python import GopherAgent, GopherAgentConfig

# Create configuration with server config
config = (GopherAgentConfig.builder()
    .provider("AnthropicProvider")
    .model("claude-3-haiku-20240307")
    .server_config('{"mcpServers": [...]}')
    .build())

# Create agent
agent = GopherAgent.create(config)
try:
    response = agent.run("What is the weather?")
    print(response)
finally:
    agent.dispose()

Using Convenience Methods

from gopher_mcp_python import GopherAgent

# Create with API key (shorthand)
agent = GopherAgent.create_with_api_key(
    provider="AnthropicProvider",
    model="claude-3-haiku-20240307",
    api_key="your-api-key"
)

# Or with server config
agent = GopherAgent.create_with_server_config(
    provider="AnthropicProvider",
    model="claude-3-haiku-20240307",
    server_config='{"mcpServers": [...]}'
)

Getting Detailed Results

from gopher_mcp_python import GopherAgent

with GopherAgent.create(config) as agent:
    result = agent.run_detailed("What time is it?")

    if result.is_success():
        print(f"Response: {result.response}")
        print(f"Iterations: {result.iteration_count}")
        print(f"Tokens used: {result.tokens_used}")
    elif result.is_timeout():
        print(f"Request timed out: {result.error_message}")
    else:
        print(f"Error: {result.error_message}")

API Reference

GopherAgent

Main class for interacting with the gopher-mcp-python native library.

Static Methods

  • GopherAgent.init() - Initialize the library (called automatically)
  • GopherAgent.shutdown() - Shutdown the library
  • GopherAgent.is_initialized() - Check if library is initialized
  • GopherAgent.create(config) - Create an agent with configuration
  • GopherAgent.create_with_api_key(provider, model, api_key) - Convenience method
  • GopherAgent.create_with_server_config(provider, model, server_config) - Convenience method

Instance Methods

  • agent.run(query, timeout_ms=60000) - Run a query and get response string
  • agent.run_detailed(query, timeout_ms=60000) - Run a query and get AgentResult
  • agent.dispose() - Release resources
  • agent.is_disposed() - Check if agent is disposed

GopherAgentConfig

Configuration class with builder pattern.

config = (GopherAgentConfig.builder()
    .provider("AnthropicProvider")  # Required
    .model("claude-3-haiku-20240307")  # Required
    .api_key("key")  # Either api_key or server_config required
    .server_config("{...}")  # Either api_key or server_config required
    .build())

AgentResult

Result class with status and metadata.

  • result.response - Response text
  • result.status - AgentResultStatus enum
  • result.iteration_count - Number of iterations
  • result.tokens_used - Tokens consumed
  • result.error_message - Error message (if applicable)
  • result.is_success() - Check if successful
  • result.is_error() - Check if error
  • result.is_timeout() - Check if timeout

Provider OAuth Elicitation

Provider OAuth requested during a tool call is handled automatically by default. For URL-mode elicitation, the SDK opens the authorization URL when possible, prints it as a fallback, waits for the user to finish the browser flow, and then lets the native agent retry the tool call.

No example-level elicitation configuration is required:

agent = GopherAgent.create_with_url(provider, model, mcp_url)

Use GopherAgentCreateOptions only when you need a custom synchronous handler or want to disable browser opening while still printing the URL:

from gopher_mcp_python import GopherAgentCreateOptions

agent = GopherAgent.create_with_url(
    provider,
    model,
    mcp_url,
    GopherAgentCreateOptions(
        elicitation={
            "open_browser": False,
            "handler": lambda request: "accept",
        },
    ),
)

First-step MCP server OAuth is controlled separately by the oauth create option. Setting oauth={"mode": "disabled"} skips SDK OAuth discovery for the MCP endpoint but still leaves provider elicitation enabled.

Exceptions

  • AgentError - Base exception for agent errors
  • ApiKeyError - Invalid API key
  • ConnectionError - Connection failed
  • TimeoutError - Operation timed out

Development

Running Tests

pytest

For deterministic OAuth auto verification with a local custom IdP and local MCP server/gateway endpoints, see docs/oauth-auto-custom-idp.md.

Code Formatting

This project uses Black for code formatting and Ruff for linting.

Format code:

black .

Check formatting without modifying:

black --check .

Run linter:

ruff check .

Fix linting issues:

ruff check --fix .

Building the Native Library

./build.sh

Clean Build

./build.sh --clean

OAuth scope selection

Automatic OAuth uses the challenge's scope when present, otherwise explicit oauth.scopes, then the protected resource's scopes_supported. If none are available, the request omits scope. The authorization server's realm-wide scope list is never used as a default. An explicit empty list means omit scope.

Web applications managing their own redirects can reuse the same policy:

from gopher_mcp_python import select_oauth_scopes

scopes = select_oauth_scopes(
    challenge_scopes=challenge_scopes,  # None if absent; [] if explicitly empty
    resource_scopes=resource_scopes,
)

Use this result for both client registration and the authorization request, omitting the scope field when the result is empty. This helper performs no network requests or browser operations.

Automatic OAuth preserves the protected-resource metadata's resource identifier through authorization, code exchange, and token refresh. It can differ from the MCP connection URL. Applications using exchange_oauth_code_for_token or refresh_oauth_token directly can pass it with the resource keyword argument.

Applications with a guarded or asynchronous HTTP client can prepare the same code-exchange request without letting the SDK send it:

from gopher_mcp_python.oauth_token_exchange import build_oauth_code_exchange_request

request = build_oauth_code_exchange_request(
    code=code,
    redirect_uri=redirect_uri,
    code_verifier=code_verifier,
    token_endpoint=token_endpoint,
    client_id=client_id,
    resource=resource,
    client_secret=client_secret,
    token_endpoint_auth_method=token_endpoint_auth_method,
)
# Send request.data as form data to request.token_endpoint, with request.headers,
# using your application's HTTP client and URL validation.

The built-in exchange helper uses this builder too. Public clients and client_secret_post/client_secret_basic authentication are supported.

Environment Variables

  • GOPHER_MCP_PYTHON_LIBRARY_PATH - Custom path to native library
  • DEBUG - Enable debug output for library loading

License

See LICENSE file for details.

Metadata

Release files for gopher-mcp-python 0.1.40.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gopher-mcp-python 0.1.40.2
File Size Uploaded Provenance Actions
gopher_mcp_python-0.1.40.2.tar.gz 98.2 kB Without provenance Details for gopher_mcp_python-0.1.40.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gopher-mcp-python 0.1.40.2
File Interpreter ABI Platform Actions
gopher_mcp_python-0.1.40.2-py3-none-any.whl Python 3 none any Details for gopher_mcp_python-0.1.40.2-py3-none-any.whl

Total release size: 175.5 kB

Release files / gopher_mcp_python-0.1.40.2.tar.gz

Download URL gopher_mcp_python-0.1.40.2.tar.gz
Size 98.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e5e12f0dd0f684082ea1a0fff4ac4b6735f9eb4d80827a0282124d4a2e2e6f89
BLAKE2b-256 checksum
How to use checksums
ef01a252e437a71c2a159ed4d1b089dff753f633ca01f7cb04cb04a81974468c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / gopher_mcp_python-0.1.40.2-py3-none-any.whl

Download URL gopher_mcp_python-0.1.40.2-py3-none-any.whl
Size 77.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
460b21f337a0c7b22ddad9af8b94f6fc87c65083ce0de2fc20c77c56ecdecafc
BLAKE2b-256 checksum
How to use checksums
806b2edd10f30c237f12972da47819a806971330f077e58621bd54fe26aca5b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for gopher-mcp-python 0.1.40.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page