Foxy Contexts

Foxy Contexts provides a fluent, chainable app.Builder API that abstracts the Model Context Protocol server lifecycle, allowing developers to register tools, resources, and prompts declaratively without writing boilerplate JSON-RPC handlers. The builder leverages Uber's fx dependency injection framework to wire components, manage initialization order, and handle server lifecycle events (startup, shutdown, session management) automatically.

Foxy Contexts abstracts transport layer complexity by providing pluggable transport implementations for Stdio (stdin/stdout), Server-Sent Events (SSE), and Streamable HTTP (beta). Each transport handles the protocol-specific framing, message serialization, and bidirectional communication while the core MCP logic remains transport-agnostic. Developers select a transport via builder configuration without changing tool/resource definitions.

Tools are registered via a declarative API that captures function name, description, input JSON schema, and a Go callback function. Foxy Contexts automatically generates MCP-compliant tool metadata and routes incoming JSON-RPC tool_call requests to the appropriate callback, handling argument deserialization and error propagation. The schema is derived from Go struct tags or explicitly defined, enabling type-safe tool invocation.

Resources are exposed either as static data (defined at registration time) or dynamically via resource provider functions that compute data on-demand. Foxy Contexts registers resources with URI patterns and metadata, then routes resource_read requests to either static data or provider callbacks. Providers receive context (client session info, resource URI) and return resource content, enabling context-aware data serving.

Prompts are registered as reusable templates with variable placeholders and descriptions. Clients can request available prompts and invoke prompt_complete to fill in variables with runtime values. Foxy Contexts handles prompt metadata registration and routes completion requests to user-defined completion callbacks that substitute variables and return the filled prompt. Supports multi-argument prompts with type hints.

Foxy Contexts manages server lifecycle events (initialization, client connection, disconnection) and maintains per-session context. The framework provides hooks for session setup/teardown and passes session context to tool callbacks and resource providers, enabling per-client state isolation and resource cleanup. Built on fx lifecycle management, ensuring deterministic startup/shutdown ordering.

Foxy Contexts includes foxytest, a testing utility that enables functional testing of MCP servers without network overhead. Tests can invoke tools, request resources, and complete prompts directly against the server instance using a test client API. Foxytest provides matching and diffing utilities for assertions, process management for spawning test servers, and structured test suite organization.

Foxy Contexts leverages Uber's fx framework to manage component dependencies and initialization order. Tools, resources, and prompts are registered as fx modules, and the builder automatically constructs the dependency graph. This enables constructor injection for tool/resource callbacks, automatic lifecycle management, and composable server configurations. Developers can extend the fx graph with custom modules for application-specific dependencies.

Foxy Contexts implements the Model Context Protocol specification, ensuring all registered tools, resources, and prompts conform to MCP's JSON-RPC message format, request/response schemas, and error handling conventions. The framework handles protocol-level concerns (message routing, schema validation, error serialization) transparently, allowing developers to focus on business logic. Regular updates maintain compatibility with MCP specification versions.

Foxy Contexts uses a fluent builder pattern for server configuration, allowing developers to chain method calls to register tools, resources, prompts, and configure transports. The builder accumulates configuration and constructs the server on a final build() call. This approach provides a clean, readable API that mirrors the declarative nature of MCP component registration and enables IDE autocomplete for available configuration options.