# strowk/foxy-contexts architecture

> Architecture diagram of the GitHub repository strowk/foxy-contexts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strowk/foxy-contexts
- Repository: https://github.com/strowk/foxy-contexts

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Code
    subgraph "User Code" 
        Client["External Client\n(examples/.../main.go)"]:::user
    end

    %% Transport Layer
    subgraph "Transport Layer" 
        StdIO["stdio Transport"]:::infra
        SSE["SSE Transport"]:::infra
        HTTP["Streamable HTTP Transport"]:::infra
        TransportIfc["Transport Interface"]:::infra
    end

    %% JSONRPC2 Router
    subgraph "JSONRPC2 Router"
        Router["JSONRPC2 Router"]:::infra
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        ServerCore["Server Core"]:::infra
        ServerOptions["Server Options"]:::infra
        ServerVersion["Version Metadata"]:::infra
        ServerTransportGlue["Server-Transport Glue"]:::infra
    end

    %% Dependency Injection Container
    subgraph "DI Container"
        fxApp["fx.App (foxy_app.go)"]:::di
    end

    %% Declarative Modules
    subgraph "Declarative Modules"
        Tools["Tool Definitions & Mux"]:::declarative
        Resources["Resource Definitions & Mux"]:::declarative
        Prompts["Prompt Definitions & Mux"]:::declarative
        Providers["Resource Providers"]:::declarative
        Completion["Module Completion Helpers"]:::declarative
    end

    %% Protocol Types & Validation
    subgraph "Protocol Types & Validation"
        MCPTypes["MCP Method/Schema Types"]:::declarative
        InputValidation["Input Schema Validation"]:::declarative
    end

    %% Event Logging
    subgraph "Event Logging"
        EventAdapters["Event Adapters"]:::infra
        LoggerIntegration["Logger Integration"]:::infra
    end

    %% Functional Test Harness
    subgraph "Functional Test Harness"
        TestSuite["Test Suite Setup"]:::test
        TestTransportStdio["Mock stdio Transport"]:::test
        TestTransportHTTP["Mock HTTP Transport"]:::test
        TestMocks["Test Mocks"]:::test
    end

    %% Connections
    Client -->|JSONRPC2 over stdio| StdIO
    Client -->|JSONRPC2 over SSE| SSE
    Client -->|JSONRPC2 over HTTP| HTTP

    StdIO -->|requests| Router
    SSE -->|requests| Router
    HTTP -->|requests| Router

    Router -->|calls| ServerCore
    ServerCore -->|uses options| ServerOptions
    ServerCore -->|reports version| ServerVersion
    ServerCore -->|routes via| ServerTransportGlue

    ServerCore -->|invokes callbacks| Tools
    ServerCore -->|invokes callbacks| Resources
    ServerCore -->|invokes callbacks| Prompts

    Tools -->|validate/input| InputValidation
    Resources -->|validate/input| InputValidation
    Prompts -->|validate/input| InputValidation

    Router -->|parses schemas| MCPTypes
    InputValidation -->|uses schemas| MCPTypes

    fxApp -->|provides| TransportIfc
    fxApp -->|provides instances of| StdIO
    fxApp -->|provides instances of| SSE
    fxApp -->|provides instances of| HTTP
    fxApp -->|provides| Router
    fxApp -->|provides| ServerCore
    fxApp -->|provides| Tools
    fxApp -->|provides| Resources
    fxApp -->|provides| Prompts
    fxApp -->|provides| Providers
    fxApp -->|provides| Completion
    fxApp -->|provides| MCPTypes
    fxApp -->|provides| InputValidation
    fxApp -->|provides| EventAdapters
    fxApp -->|provides| LoggerIntegration

    ServerCore -->|logs events| EventAdapters
    ServerCore -->|uses logger| LoggerIntegration

    %% Test Harness Flow
    TestSuite -->|uses mock| TestTransportStdio
    TestSuite -->|uses mock| TestTransportHTTP
    TestSuite -->|includes| TestMocks

    TestTransportStdio -->|requests| Router
    TestTransportHTTP -->|requests| Router

    %% Click Events
    click Client "https://github.com/strowk/foxy-contexts/blob/main/examples/[example_name]/main.go"
    click StdIO "https://github.com/strowk/foxy-contexts/blob/main/pkg/stdio/stdio_transport.go"
    click SSE "https://github.com/strowk/foxy-contexts/blob/main/pkg/sse/sse_transport.go"
    click HTTP "https://github.com/strowk/foxy-contexts/blob/main/pkg/streamable_http/streamable_http_transport.go"
    click TransportIfc "https://github.com/strowk/foxy-contexts/blob/main/pkg/server/transport.go"
    click Router "https://github.com/strowk/foxy-contexts/blob/main/pkg/jsonrpc2/router.go"
    click ServerCore "https://github.com/strowk/foxy-contexts/blob/main/pkg/server/server.go"
    click ServerOptions "https://github.com/strowk/foxy-contexts/blob/main/pkg/server/option.go"
    click ServerVersion "https://github.com/strowk/foxy-contexts/blob/main/pkg/server/version.go"
    click ServerTransportGlue "https://github.com/strowk/foxy-contexts/blob/main/pkg/server/transport.go"
    click fxApp "https://github.com/strowk/foxy-contexts/blob/main/pkg/app/foxy_app.go"
    click Tools "https://github.com/strowk/foxy-contexts/blob/main/pkg/fxctx/tool.go"
    click Resources "https://github.com/strowk/foxy-contexts/blob/main/pkg/fxctx/resource.go"
    click Prompts "https://github.com/strowk/foxy-contexts/blob/main/pkg/fxctx/prompt.go"
    click Providers "https://github.com/strowk/foxy-contexts/blob/main/pkg/fxctx/resource_provider.go"
    click Completion "https://github.com/strowk/foxy-contexts/blob/main/pkg/fxctx/complete_mux.go"
    click MCPTypes "https://github.com/strowk/foxy-contexts/blob/main/pkg/mcp/method.go"
    click InputValidation "https://github.com/strowk/foxy-contexts/blob/main/pkg/toolinput/tool_input_schema.go"
    click EventAdapters "https://github.com/strowk/foxy-contexts/blob/main/pkg/foxy_event/event.go"
    click LoggerIntegration "https://github.com/strowk/foxy-contexts/blob/main/pkg/foxy_event/logger.go"
    click TestSuite "https://github.com/strowk/foxy-contexts/blob/main/pkg/foxytest/testsuite.go"
    click TestTransportStdio "https://github.com/strowk/foxy-contexts/blob/main/pkg/foxytest/transport_stdio.go"
    click TestTransportHTTP "https://github.com/strowk/foxy-contexts/blob/main/pkg/foxytest/transport_streamable_http.go"
    click TestMocks "https://github.com/strowk/foxy-contexts/blob/main/pkg/foxytest/mock/testrunner_mock.go"

    %% Styles
    classDef infra fill:#D6EAF8,stroke:#3498DB
    classDef declarative fill:#D5F5E3,stroke:#27AE60
    classDef di fill:#FCF3CF,stroke:#F1C40F
    classDef user fill:#F2F3F4,stroke:#ABB2B9
    classDef test fill:#E8DAEF,stroke:#8E44AD
```
