Substrate - MCP Foundation Layer

Substrate provides the foundation for building production-grade Model Context Protocol (MCP) servers. It includes base classes, documentation, and patterns that ensure consistent, reliable implementations.

Overview

Substrate is:

Foundation Layer: Base classes and interfaces for all MCP servers
Documentation Server: Serves methodology and architecture documentation
Pattern Library: Common patterns for MCP implementation
Passive Component: Provides structure but no active functionality

Features

Base MCP Class: Standard patterns for all MCP servers
Response Builders: Structured response creation
Error Handling: Consistent error patterns
Progress Tracking: Real-time operation feedback
Sampling Support: Intelligent assistance integration
Documentation Loading: Flexible documentation system

Installation

As a Dependency

For use in your MCP server:

pip install substrate-mcp

Or in your pyproject.toml:

dependencies = [
    "substrate-mcp>=1.0.0",
    "fastmcp>=0.1.0"
]

For Development

git clone https://github.com/ivan-saorin/substrate
cd substrate
pip install -e .

Usage

Creating an MCP Server

from substrate import SubstrateMCP

class YourServer(SubstrateMCP):
    def __init__(self):
        super().__init__(
            name="your_mcp",
            version="1.0.0",
            description="Your MCP description"
        )
        self._register_tools()
    
    def _register_tools(self):
        @self.tool()
        async def your_tool(ctx, param: str):
            """Tool description"""
            result = await self.process(param)
            return self.create_response(
                success=True,
                data=result
            )

Running Substrate Server

# Run the documentation server
python -m substrate

# Or with custom docs
SUBSTRATE_DOCS_DIR=/path/to/docs python -m substrate

Docker Usage

FROM python:3.12-slim

# Copy substrate
COPY substrate /substrate

# Copy your MCP
COPY your-mcp /app

WORKDIR /app

# Install both
RUN pip install -e /substrate && pip install -e .

CMD ["python", "-m", "your_mcp"]

Documentation System

Substrate can serve different documentation sets:

Bundled Docs: Default examples included with substrate
Custom Docs: Your own methodology and architecture

Custom Documentation

Mount your documentation at runtime:

# Docker
docker run -v ./my-docs:/substrate-docs substrate-mcp

# Local
export SUBSTRATE_DOCS_DIR=./my-docs
python -m substrate

Your documentation directory should contain:

atlas.md - Development methodology
system-design.md - System architecture
component-map.json - Component registry

Base Classes

SubstrateMCP

The foundation for all MCP servers:

class SubstrateMCP(FastMCP):
    """Base class providing:
    - Response building
    - Error handling
    - Progress tracking
    - Sampling support
    """

Response Patterns

# Success response
return self.create_response(
    success=True,
    data={"result": value},
    message="Operation completed"
)

# Error response
return self.create_error_response(
    error="Clear error message",
    error_type="validation",
    suggestions=["Try this", "Check that"]
)

Progress Tracking

async with self.progress_context("operation") as progress:
    await progress(0.1, "Starting...")
    # ... work ...
    await progress(0.5, "Halfway...")
    # ... more work ...
    await progress(1.0, "Complete!")

Integration with AKAB

Substrate is designed to work with AKAB for A/B testing:

# In your MCP
result = await ctx.call_tool(
    "akab_quick_compare",
    prompt="Your prompt",
    providers=["anthropic_m", "openai_l"]
)

Best Practices

Production-Grade Only: Real implementations, no mocks
Clear Separation: Each MCP does one thing well
Explicit Interfaces: No implicit behaviors
Structured Errors: Always provide actionable feedback
Clean Logging: Use stderr, never stdout

Common Issues

Stdout Pollution

MCP uses JSON-RPC over stdio. Any print() breaks the protocol.

Solution: Log to stderr

logging.basicConfig(stream=sys.stderr)

AsyncIO Conflicts

FastMCP manages its own event loop.

Solution: Don't use asyncio.run()

def main():
    server = YourServer()
    server.run()  # Let FastMCP handle async

Examples

See the included example documentation:

docs/atlas.md - Example development methodology
docs/system-design.md - Example system architecture
docs/component-map.json - Example component structure

Contributing

Follow the Atlas methodology
Ensure all tests pass
Update documentation as needed
Submit PR with clear description

License

MIT License - see LICENSE file for details