How strowk/foxy-contexts works
Project type and purpose
• This is an open-source Golang library (“Foxy Contexts”) for building MCP (Model Context Protocol) servers in a declarative, dependency-injected fashion.
• It provides primitives for defining MCP Tools, Resources, Prompts, wiring them into an application, and exposing them over various transports (stdio, SSE, HTTP).
File structure
• Top-level directories:
• pkg/ — core library packages (app, fxctx, mcp, transports, server, JSONRPC2 router, session, events, testing)
• internal/ — internal utilities
• examples/ — standalone sample MCP servers (one-file Go apps using the library)
• docs/ — Hugo site content for documentation
• tests/ — integration/lifecycle tests
• The heart of the architecture lives in pkg/:
• app — Builder abstraction on top of uber/fx
• fxctx — declarative definitions for tools, resources, prompts, providers
• mcp — protocol data structures (Tool, CallToolResult, ToolInputSchema)
• jsonrpc2 — low-level JSONRPC2 request/response routing
• server — glue code to start an MCP server with fx lifecycle
• stdio/sse/streamable_http — transport implementations
• session — session context and lifecycle management
• foxy_event — event logging adapters
• foxytest — functional testing harness
Key insights from README
• Emphasizes declarative registration of Tools/Resources/Prompts via app.Builder.
• Under the hood uses Uber’s fx DI container to assemble modules.
• Supports multiple transports (stdio, SSE, streamable HTTP).
• Provides a testing package (foxytest) to write functional tests.
• Examples show a minimal main.go that calls NewBuilder().WithTool(...).WithTransport(...).Run().
a. External Client (Model Context Inspector, CLI, or any JSONRPC2 client)
b. Transport Layer (stdio, SSE, HTTP transport)
c. JSONRPC2 Router (pkg/jsonrpc2)
d. MCP Server Core (pkg/server + session.Manager)
e. Dependency Injection Container (uber.fx)
f. Declarative Modules (pkg/fxctx: Tools, Resources, Prompts, Providers)
g. Protocol Types & Validation (pkg/mcp, pkg/toolinput)
h. Event Logging (pkg/foxy_event)
i. Functional Test Harness (pkg/foxytest)
j. User-defined Components (in examples or user code)
Relationships and interactions
• Client <→ Transport: JSONRPC2 messages flow over stdio/SSE/HTTP
• Transport → JSONRPC2 Router: inbound requests are parsed and dispatched
• Router → MCP Server Core: routes “listTools”, “callTool”, etc., to handlers
• MCP Server Core → Session Manager: maintains per-client session context
• Server Core + Session → Declarative Modules: invokes user-registered tool/resource/prompt callbacks
• Declarative Modules → Protocol Types & Validation: use mcp structs and toolinput for request/response schemas
• All components wired into fx DI container via app.Builder
• Event Logging sprinkled in via foxy_event, zap logger injected into fx
• pkg/foxytest drives a faux Transport + Router to perform functional tests
Architectural patterns and principles
• Dependency Injection (uber.fx) to assemble modules
• Inversion of Control: user code merely registers Tools/Resources/Prompts
• Modular transports implementing a Transport interface
• JSONRPC2 router isolates protocol parsing from business logic
• Session abstraction isolates per-client state
• Pluggable validation via toolinput schemas
• Testing abstraction via foxytest that reuses same DI wiring
Essential elements to capture
• fx.App container as central “hub” connecting transports, server, logger, modules
• Protocol boundary (JSONRPC2) clearly separated from business logic
• Pluggable modules via fxctx and mcp types
• Multi-transport support under a common interface
• Session manager handling per-client state
• foxytest hooking into the same pipeline for testing