Interoperable Context Service

A multi-language, multi-framework MCP (Model Context Protocol) server implementation for exposing conversation context via resources and providing save tools. This project demonstrates feature parity across multiple languages (TypeScript, Rust, Python) and frameworks (Official SDKs, FastMCP, XMCP, MCP Framework).

Overview

The Interoperable Context Service enables LLMs to:

Retrieve conversation context via MCP resources using standardized URI patterns
Save conversation context with rich metadata through MCP tools
Understand when and how to save context via MCP prompts

This multi-language, multi-framework implementation provides:

Clean separation of concerns through a mono-repo structure
Feature parity across 6 different implementations
Comparison of official MCP SDKs vs. community frameworks
Local filesystem storage with identical JSON data formats
Comprehensive test framework for cross-language/framework validation
Performance benchmarking across all implementations

Implementations

This project includes six complete MCP server implementations:

Official SDK Implementations

Implementation	Port	Language	SDK/Framework	Status
TypeScript SDK Server	3000	TypeScript	Official MCP TypeScript SDK	✅ Production Ready
Rust SDK Server	3003	Rust	Official MCP Rust SDK	✅ Production Ready
Python SDK Server	3005	Python	Official MCP Python SDK	✅ Production Ready

Community Framework Implementations

Implementation	Port	Language	SDK/Framework	Status
FastMCP Server	3001	TypeScript	FastMCP	✅ Production Ready
XMCP Server	3002	TypeScript	XMCP	✅ Production Ready
MCP Framework Server	3003*	TypeScript	MCP Framework	⚠️ In Development

*Note: MCP Framework default port (3003) conflicts with Rust server. Set MCP_PORT environment variable to use a different port when running both simultaneously.

All six implementations:

Expose identical MCP protocol interfaces
Use the same JSON data format for conversations
Support the same tools and resources
Can read each other's saved conversation files
Pass the same compliance test suites
Demonstrate different approaches to building MCP servers

Architecture

interoperable-context-service/
├── packages/
│   ├── mcp-server-typescript/   # TypeScript MCP server - Official SDK (port 3000)
│   ├── mcp-server-rust/         # Rust MCP server - Official SDK (port 3003)
│   ├── mcp-server-python/       # Python MCP server - Official SDK (port 3005)
│   ├── mcp-server-fastmcp/      # TypeScript MCP server - FastMCP (port 3001)
│   ├── mcp-server-xmcp/         # TypeScript MCP server - XMCP (port 3002)
│   ├── mcp-server-mcp-framework/ # TypeScript MCP server - MCP Framework (port 3003*)
│   ├── mcp-test-framework/      # Cross-language/framework test framework
│   └── shared-types/            # Shared TypeScript type definitions
├── data/                        # Local storage for conversations (gitignored)
├── docs/                        # Documentation and examples
├── test-reports/                # Published test reports and benchmarks
└── agent-os/                    # Specifications and planning

Components

Official SDK Implementations

MCP Server (TypeScript SDK): Reference implementation using the official MCP TypeScript SDK. Demonstrates best practices for the official SDK with Express-based HTTP transport.

MCP Server (Rust): High-performance server implementation using the official MCP Rust SDK. Provides identical functionality with Rust's performance characteristics and safety guarantees.

MCP Server (Python): Python-based server implementation using the official MCP Python SDK. Leverages Python's ecosystem and async patterns with asyncio.

Community Framework Implementations

MCP Server (FastMCP): Implementation using the FastMCP framework, which provides a simplified decorator-based API for building MCP servers quickly.

MCP Server (XMCP): Implementation using the XMCP framework, featuring file-system based routing and automatic discovery of MCP primitives.

MCP Server (MCP Framework): Implementation using the MCP Framework, which offers directory-based organization and class-based MCP primitives.

Supporting Components

Test Framework: Comprehensive cross-language/framework testing framework that validates compliance, performance, reliability, security, and stress testing across all six implementations.

Shared Types: Common TypeScript interfaces and type definitions used across all TypeScript-based packages.

Storage Layer: Isolated filesystem operations for conversation persistence. Uses identical JSON format across all implementations enabling full interoperability.

Quick Start

Prerequisites

For TypeScript: Node.js >= 18.0.0, pnpm >= 8.0.0
For Rust: Rust >= 1.70.0, Cargo
For Python: Python >= 3.12, Poetry >= 1.5.0

Installation

# Clone the repository
git clone <repository-url>
cd interoperable-context-service

# Install TypeScript dependencies
pnpm install

# Install Rust dependencies
cd packages/mcp-server-rust && cargo build --release

# Install Python dependencies
cd packages/mcp-server-python && poetry install

Running the Servers

Official SDK Servers

TypeScript SDK Server (Port 3000):

cd packages/mcp-server-typescript
pnpm build
node dist/index.js

# Health check: http://localhost:3000/health
# MCP endpoint: http://localhost:3000/mcp

Rust Server (Port 3003):

cd packages/mcp-server-rust
cargo run --release

# Health check: http://localhost:3003/health
# MCP endpoint: http://localhost:3003/mcp

Python Server (Port 3005):

cd packages/mcp-server-python
poetry run python -m mcp_server_python.main

# Health check: http://localhost:3005/health
# MCP endpoint: http://localhost:3005/mcp

Community Framework Servers

FastMCP Server (Port 3001):

cd packages/mcp-server-fastmcp
pnpm build
node dist/index.js

# Health check: http://localhost:3001/health
# MCP endpoint: http://localhost:3001/mcp

XMCP Server (Port 3002):

cd packages/mcp-server-xmcp
pnpm build
node dist/index.js

# Health check: http://localhost:3002/health
# MCP endpoint: http://localhost:3002/mcp

MCP Framework Server (Port 3003):

cd packages/mcp-server-mcp-framework
pnpm build
# Note: Default port 3003 conflicts with Rust server
# Set MCP_PORT to use a different port: MCP_PORT=3006 node dist/index.js
node dist/index.js

# Health check: http://localhost:3003/health
# MCP endpoint: http://localhost:3003/mcp

Configuration

All implementations support the same environment variables:

# Set custom data directory
export MCP_DATA_DIR=/path/to/data/conversations

# Set HTTP server port
export MCP_PORT=8080

# Set HTTP server host
export MCP_HOST=0.0.0.0

# Enable debug logging
export MCP_DEBUG=true

MCP Protocol Features

Resources

URI Pattern: context://conversation/{id}

Retrieve full conversation context by conversation ID. Resources return complete conversation data including all messages and metadata.

Example:

context://conversation/debug-react-state-2025-10-30

Tools

save_conversation_context: Save a conversation with LLM-generated metadata.

Parameters:

id (string, required): Unique conversation identifier
timestamp (string, required): ISO 8601 timestamp
messages (array, required): Array of conversation messages
metadata (object, optional): LLM-generated metadata (title, summary, tags)

Example invocation:

{
  "id": "debug-react-state-2025-10-30",
  "timestamp": "2025-10-30T14:30:00.000Z",
  "messages": [
    {
      "role": "user",
      "content": "I'm having trouble with React state not updating...",
      "timestamp": "2025-10-30T14:25:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Let's check if you're mutating state directly...",
      "timestamp": "2025-10-30T14:26:00.000Z"
    }
  ],
  "metadata": {
    "title": "Debugging React State Update Issue",
    "summary": "Identified state mutation issue and provided solution.",
    "tags": ["react", "debugging", "state-management"]
  }
}

Prompts

context_save_guidance: Provides comprehensive guidance to LLMs on when to save context and how to generate appropriate metadata.

The prompt includes:

When to save context (after meaningful interactions, significant decisions, etc.)
What metadata to generate (titles, summaries, tags)
Examples of well-formed conversation saves
Model-agnostic instructions for GPT-4, Claude, and other LLMs

Data Format Compatibility

All six implementations use an identical JSON format for conversation storage, ensuring full interoperability:

{
  "id": "debug-react-state-2025-10-30",
  "timestamp": "2025-10-30T14:30:00.000Z",
  "messages": [
    {
      "role": "user",
      "content": "Message content",
      "timestamp": "2025-10-30T14:25:00.000Z"
    }
  ],
  "metadata": {
    "title": "Conversation Title",
    "summary": "Brief summary",
    "tags": ["tag1", "tag2"]
  }
}

This means:

A conversation saved by any implementation can be read by any other implementation
Full interoperability across all languages (TypeScript, Rust, Python)
Full interoperability across all frameworks (Official SDKs, FastMCP, XMCP, MCP Framework)
Seamless migration between different implementations

Development

Mono-repo Structure

This project uses pnpm workspaces for mono-repo management:

{
  "workspaces": ["packages/*"]
}

Packages can reference each other using the workspace:* protocol in their dependencies.

Available Scripts

Run these scripts from the repository root:

# Build all packages
pnpm build

# Clean and rebuild
pnpm build:clean

# Run tests across all packages
pnpm test

# Run tests in watch mode
pnpm test:watch

# Lint all packages
pnpm lint

# Format code
pnpm format

# Check formatting
pnpm format:check

# Type checking
pnpm typecheck

Testing

The project includes a comprehensive test framework that validates all implementations:

# Run cross-language/framework test suite
cd packages/mcp-test-framework
npm run test:all

# Test individual implementations
npm run test:typescript    # Official TypeScript SDK
npm run test:rust          # Official Rust SDK
npm run test:python        # Official Python SDK
npm run test:fastmcp       # FastMCP framework
npm run test:xmcp          # XMCP framework
npm run test:mcp-framework # MCP Framework

Test suites include:

Compliance Tests: MCP protocol adherence
Performance Tests: Latency and throughput benchmarks
Reliability Tests: Error handling and recovery
Security Tests: Input validation and sanitization
Stress Tests: High load and concurrent operations

Python-Specific Development

cd packages/mcp-server-python

# Run tests
poetry run pytest tests/ -v

# Run with coverage
poetry run pytest tests/ -v --cov=mcp_server_python --cov-report=term-missing

# Type checking
poetry run mypy mcp_server_python/ --strict

# Code formatting
poetry run black mcp_server_python/ tests/

# Linting
poetry run ruff check mcp_server_python/ tests/

Rust-Specific Development

cd packages/mcp-server-rust

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo test

# Build optimized release
cargo build --release

# Check code
cargo clippy
cargo fmt --check

Data Storage

Conversations are stored as JSON files in the configured data directory:

data/
└── conversations/
    ├── conversation-id-1.json
    ├── conversation-id-2.json
    └── ...

Each conversation file is pretty-printed for human readability:

{
  "id": "debug-react-state-2025-10-30",
  "timestamp": "2025-10-30T14:30:00.000Z",
  "messages": [...],
  "metadata": {...}
}

Storage Abstraction

The storage layer is intentionally isolated in dedicated modules to prepare for future abstraction. All storage operations go through a consistent interface, making it easy to swap the implementation later (e.g., for S3, database, etc.).

Package Documentation

Each package has its own detailed README:

Official SDK Implementations

mcp-server-typescript: TypeScript MCP server using official SDK
mcp-server-rust: Rust MCP server using official SDK
mcp-server-python: Python MCP server using official SDK

Community Framework Implementations

mcp-server-fastmcp: FastMCP framework implementation
mcp-server-xmcp: XMCP framework implementation
mcp-server-mcp-framework: MCP Framework implementation

Supporting Packages

mcp-test-framework: Cross-language/framework test framework
shared-types: Shared TypeScript type definitions

Performance Comparison

For detailed performance benchmarks and comparison data across all implementations, see:

Latest Test Report - Live GitHub Pages site with comprehensive test results

Performance Rankings (from latest test)

Rust MCP Server (92.6% overall) - Best all-around performer
- 100% compliance, 100% reliability, 100% security
- Highest throughput: 3,571 req/s
- Fast cold start: 510ms
FastMCP Server (85.3% overall) - Best community framework
- 100% compliance, 100% security
- 94.7% test pass rate
- Good throughput: 1,785 req/s
TypeScript SDK Server (79.7% overall) - Solid official SDK implementation
- 100% security, 87.5% compliance
- 89.5% test pass rate
- Strong throughput: 1,923 req/s
XMCP Server (78.5% overall) - File-system routing approach
- 100% security, 87.5% compliance
- Similar performance to TypeScript SDK
MCP Framework Server (30.0% overall) - Early development stage
- Currently undergoing stabilization
Python SDK Server (26.5% overall) - Under active development
- Good cold start for Python: 1,012ms
- Async I/O foundation in place

Design Decisions

Why Multi-Language and Multi-Framework?

Six different implementations demonstrate:

True Interoperability: Same protocol, different languages and frameworks
Performance Comparison: Benchmark official SDKs vs. community frameworks
Developer Choice: Choose the language and framework that fits your needs
Protocol Validation: Cross-implementation testing ensures specification compliance
Framework Evaluation: Compare approaches (decorator-based, file-system routing, directory organization)
Best Practices: Learn from multiple implementation patterns

Why Mono-repo?

The mono-repo structure with pnpm workspaces provides:

Shared dependencies: Common dev dependencies at the root level
Type safety: Compile-time checking across packages
Easier refactoring: Change interfaces in one place
Clear boundaries: Separate concerns while maintaining cohesion

Why Official SDKs AND Community Frameworks?

The project includes both approaches:

Official SDKs (TypeScript, Rust, Python):

Specification compliance: Built by the MCP specification authors
Active maintenance: Regular updates and improvements
Community support: Growing ecosystem of tools and clients
Type safety: Full type support in each language

Community Frameworks (FastMCP, XMCP, MCP Framework):

Rapid development: Simplified APIs for faster implementation
Different patterns: Explore various architectural approaches
Innovation: Community-driven features and improvements
Comparison: Understand tradeoffs between approaches

Why Local Filesystem?

Local filesystem storage was chosen for the foundation because:

Simplicity: No external dependencies or services
Debugging: Human-readable JSON files for easy inspection
Isolation: Storage layer is separate for future abstraction
Flexibility: Easy to swap later without changing the MCP interface

Future Enhancements

Items explicitly out of scope for this foundation but planned for future:

Authentication and authorization: OAuth 2.1, API keys, etc.
Multi-user management: User scoping and isolation
Search and filtering: Query conversations by metadata
Time-based queries: "Last 7 days", "last N messages"
Advanced storage: S3, Google Cloud Storage, Azure Blob
Performance optimization: Caching, connection pooling
Distributed deployment: Horizontal scaling, load balancing
Client SDKs: Business integration libraries
Web dashboard: UI for viewing and managing conversations

Contributing

Code Style

Follow the standards defined in agent-os/standards/global/coding-style.md:

Use language-specific formatters (Prettier, rustfmt, Black)
Follow language-specific linting rules
Write clear, descriptive names
Include documentation comments for public APIs
Write tests for new features

Adding New Features

Create feature branch: feat/feature-name
Implement changes with tests across all implementations
Ensure all tests pass
Ensure code quality checks pass
Update documentation as needed
Submit pull request

Testing Requirements

Unit tests for new functions and modules
Integration tests for end-to-end workflows
Cross-language compatibility validation
All tests must pass before merging

License

Apache-2.0

References

Support

For questions, issues, or contributions:

Check the package-specific README files
Review the specifications in agent-os/specs/
Check existing issues and pull requests
Create a new issue with detailed information

Version: 0.3.0 Status: Multi-Language, Multi-Framework Implementation Last Updated: 2025-11-04

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
agent-os		agent-os
docs		docs
packages		packages
test-reports		test-reports
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
TEST-RUN-SUMMARY.md		TEST-RUN-SUMMARY.md
TESTING.md		TESTING.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
run-framework-test.js		run-framework-test.js
test-config.json		test-config.json
test-typescript-server.js		test-typescript-server.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Interoperable Context Service

Overview

Implementations

Official SDK Implementations

Community Framework Implementations

Architecture

Components

Official SDK Implementations

Community Framework Implementations

Supporting Components

Quick Start

Prerequisites

Installation

Running the Servers

Official SDK Servers

Community Framework Servers

Configuration

MCP Protocol Features

Resources

Tools

Prompts

Data Format Compatibility

Development

Mono-repo Structure

Available Scripts

Testing

Python-Specific Development

Rust-Specific Development

Data Storage

Storage Abstraction

Package Documentation

Official SDK Implementations

Community Framework Implementations

Supporting Packages

Performance Comparison

Performance Rankings (from latest test)

Design Decisions

Why Multi-Language and Multi-Framework?

Why Mono-repo?

Why Official SDKs AND Community Frameworks?

Why Local Filesystem?

Future Enhancements

Contributing

Code Style

Adding New Features

Testing Requirements

License

References

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages