Foxy Contexts MCP Server Library in Go

Overview

Foxy Contexts is a small, extensible Go library for building MCP (Model Context Protocol) server applications. It provides structure for accepting connections, maintaining context-bound state, routing incoming messages to handlers, and composing middleware-like behaviors. The library focuses on being lightweight and predictable so you can integrate context-aware handling into agents, model frontends, or long-running session services without a heavy framework.

The library is useful when you need to manage multiple independent conversation contexts, stream partial results, or bridge connection protocols to application logic. Foxy Contexts abstracts connection lifecycle and message routing so you can focus on semantic handlers and application-level behavior while still extending transport, serialization, and policy via hooks and pluggable components.

Features

• Connection lifecycle handling: accept, authenticate, and track client connections and contexts
• Context-scoped state: associate session state with context IDs and garbage-collect when finished
• Routing and handlers: map message types to handler functions for modular logic
• Extensible codecs and transports: pluggable serialization and wire protocols
• Middleware/hook support: run pre-/post-processing for things like logging, auth, or rate limits
• Lightweight runtime: minimal dependencies and predictable APIs for easy embedding
• Tooling-friendly: integrates into existing Go services or standalone servers

Installation / Configuration

Install with the standard Go module workflow. Replace “latest” with a specific version if desired.

# add to your module
go get github.com/strowk/foxy-contexts@latest

# or directly install a binary (if the repo provides one)
go install github.com/strowk/foxy-contexts/cmd/foxy-server@latest

Basic server setup (example):

package main

import (
    "log"
    fctx "github.com/strowk/foxy-contexts"
    // ...other imports for codecs, transports, etc.
)

func main() {
    // Create server with default options
    srv := fctx.NewServer()

    // Register a simple handler for "echo" message type
    srv.Handle("echo", func(ctx *fctx.Context, payload map[string]interface{}) (interface{}, error) {
        return map[string]interface{}{
            "echo": payload,
            "ctx":  ctx.ID,
        }, nil
    })

    // Start listening (blocking)
    if err := srv.ListenAndServe(":8080"); err != nil {
        log.Fatalf("server error: %v", err)
    }
}

Common configuration options:

• Address/port to bind (e.g., “:8080”)
• Default codec/serializer (JSON, MessagePack, etc.)
• TLS configuration for secure transports
• Context retention policy (timeouts, max contexts)
• Connection limits and timeouts

Available Resources

• GitHub repository: https://github.com/strowk/foxy-contexts
• README and example code in the repo demonstrate common patterns and integrations
• Source for extension points (codecs, transports, handlers) is available directly in the repo

Core conceptual types (quick reference):

Use Cases

1. Chat/Agent Sessions

   • Maintain individual conversation states for multiple clients.
   • Stream partial outputs (token-by-token) back to clients while preserving context.

   Example pattern:

   • Each conversation opens a context ID, messages are handled with a context-scoped memory store, and the server streams progressive responses until completion.

2. Multi-tenant Model Router

   • Route incoming requests to different model backends depending on tenant or context metadata.
   • Use middleware hooks to inject credentials and rate limits per tenant.

3. Plugin / Skill System

   • Build a pluggable handler ecosystem where each capability registers handlers for particular message types (e.g., “search”, “calc”, “db_query”).
   • Handlers can call out to external services while the server coordinates context and authentication.

4. Protocol Bridging

   • Bridge a WebSocket or HTTP-based client into a model-serving backend that expects context-aware sequencing.
   • Implement a transport adapter that translates wire messages into the library’s message format and vice versa.

Concrete example: registering middleware for authentication and logging

srv.Use(func(next fctx.Handler) fctx.Handler {
    return func(ctx *fctx.Context, payload any) (any, error) {
        if !authenticate(ctx) {
            return nil, fctx.ErrUnauthorized
        }
        log.Printf("ctx=%s type=%s", ctx.ID, ctx.MessageType)
        return next(ctx, payload)
    }
})

Getting Started Tips

• Start by modeling the messages and context state your application needs, then register handlers for each message type.
• Use context timeouts and max-context settings to bound resource usage.
• Implement or select codecs appropriate for your client (JSON is simplest for web clients).
• Add middleware for cross-cutting concerns (auth, logging, metrics) so handler code stays focused on business logic.

Foxy Contexts is intended to be a straightforward foundation for context-aware server logic in Go — small enough to embed, flexible enough to extend. For API details and examples, consult the repository source and examples.