MCP Server Composer

A generic Python library for composing Model Context Protocol (MCP) servers based on dependencies defined in pyproject.toml files.

Overview

The MCP Server Composer automatically discovers MCP server packages from your project dependencies and composes them into a unified server instance. This enables powerful combinations of MCP tools and prompts from multiple sources without manual integration.

Features

Automatic Discovery: Finds MCP servers in your pyproject.toml dependencies
Intelligent Composition: Combines tools, prompts, and resources from multiple servers
Conflict Resolution: Handles naming conflicts with configurable strategies
CLI Interface: Easy-to-use command-line tools
Comprehensive Testing: Full test suite with 85% coverage
FastMCP Integration: Built on the robust FastMCP framework

Installation

pip install mcp-server-composer

Quick Start

Using the Library

from mcp_server_composer import MCPServerComposer, ConflictResolution

# Create a composer
composer = MCPServerComposer(
    composed_server_name="my-unified-server",
    conflict_resolution=ConflictResolution.PREFIX
)

# Compose servers from pyproject.toml dependencies
unified_server = composer.compose_from_pyproject()

# Get composition summary
summary = composer.get_composition_summary()
print(f"Composed {summary['total_tools']} tools from {summary['source_servers']} servers")

Using the CLI

# Discover MCP servers in dependencies
python -m mcp_server_composer discover

# Compose servers into a unified server
python -m mcp_server_composer compose

# Compose with specific options
python -m mcp_server_composer compose --name my-server --conflict-resolution prefix

# Compose only specific servers
python -m mcp_server_composer compose --include server1 server2 --exclude server3

# Output results as JSON
python -m mcp_server_composer discover --output-format json

Detailed Usage

CLI Commands

`discover` - Find MCP Servers

Analyzes your pyproject.toml to find and analyze MCP server dependencies:

# Basic discovery
python -m mcp_server_composer discover

# Specify custom pyproject.toml location
python -m mcp_server_composer discover --pyproject /path/to/pyproject.toml

# Output as JSON for programmatic use
python -m mcp_server_composer discover --output-format json

Example Output:

MCP Server Discovery Results
============================

Found 2 MCP servers:

📦 jupyter-mcp-server (v1.0.0)
   🔧 Tools: 5 (notebook_create, notebook_run, etc.)
   💬 Prompts: 2 (analyze_notebook, debug_code)
   📁 Resources: 1 (notebook_templates)

📦 earthdata-mcp-server (v0.1.0)
   🔧 Tools: 3 (search_datasets, download_granules, etc.)
   💬 Prompts: 1 (analyze_climate_data)
   📁 Resources: 0

Total: 8 tools, 3 prompts, 1 resource across 2 servers

`compose` - Create Unified Server

Combines multiple MCP servers into a single unified server:

# Basic composition
python -m mcp_server_composer compose

# Custom server name and conflict resolution
python -m mcp_server_composer compose \
  --name "my-unified-server" \
  --conflict-resolution prefix

# Include/exclude specific servers
python -m mcp_server_composer compose \
  --include jupyter-mcp-server earthdata-mcp-server \
  --exclude old-server

# Save composed server to file
python -m mcp_server_composer compose \
  --output composed_server.py \
  --output-format json

Programmatic Usage

Basic Composition

from mcp_server_composer import MCPServerComposer, ConflictResolution

# Create composer with custom settings
composer = MCPServerComposer(
    composed_server_name="unified-data-server",
    conflict_resolution=ConflictResolution.PREFIX
)

# Compose from current directory's pyproject.toml
unified_server = composer.compose_from_pyproject()

# Get detailed composition information
summary = composer.get_composition_summary()
print(f"Created server with {summary['total_tools']} tools")

Advanced Configuration

from pathlib import Path
from mcp_server_composer import MCPServerComposer, ConflictResolution

# Specify custom pyproject.toml location
composer = MCPServerComposer(
    composed_server_name="my-server",
    conflict_resolution=ConflictResolution.SUFFIX
)

# Compose with filtering
unified_server = composer.compose_from_pyproject(
    pyproject_path=Path("custom/pyproject.toml"),
    include_servers=["jupyter-mcp-server", "earthdata-mcp-server"],
    exclude_servers=["deprecated-server"]
)

# Access composed tools and prompts
tools = composer.list_tools()
prompts = composer.list_prompts()
source_info = composer.get_source_info()

print(f"Tools: {', '.join(tools)}")
print(f"Sources: {', '.join(source_info.keys())}")

Discovery Only

from mcp_server_composer import MCPServerDiscovery

# Discover MCP servers without composing
discovery = MCPServerDiscovery()
servers = discovery.discover_from_pyproject("pyproject.toml")

for name, info in servers.items():
    print(f"{name}: {len(info.tools)} tools, {len(info.prompts)} prompts")

Configuration

Conflict Resolution Strategies

When multiple servers provide tools or prompts with the same name, you can choose how to resolve conflicts:

PREFIX (default): Add server name as prefix (server1_tool_name)
SUFFIX: Add server name as suffix (tool_name_server1)
OVERRIDE: Last server wins (overwrites previous)
IGNORE: Skip conflicting items
ERROR: Raise an error on conflicts

Example Conflict Resolution

# If two servers both have a "search" tool:
# PREFIX: jupyter_mcp_server_search, earthdata_mcp_server_search
# SUFFIX: search_jupyter_mcp_server, search_earthdata_mcp_server
# OVERRIDE: Only the last server's "search" tool is kept

Real-World Examples

Data Science Workflow

Create a unified MCP server combining Jupyter notebook capabilities with Earth science data access:

# pyproject.toml
[project]
dependencies = [
    "jupyter-mcp-server>=1.0.0",
    "earthdata-mcp-server>=0.1.0",
    "weather-mcp-server>=2.0.0"
]

# Discover available tools
python -m mcp_server_composer discover

# Create unified server for data science workflow
python -m mcp_server_composer compose \
  --name "data-science-server" \
  --conflict-resolution prefix \
  --output unified_server.py

This creates a server with tools like:

jupyter_create_notebook - Create analysis notebooks
earthdata_search_datasets - Find Earth science data
weather_get_forecast - Access weather data
Combined prompts for data analysis workflows

Development Environment

Combine development tools and documentation servers:

from mcp_server_composer import MCPServerComposer, ConflictResolution

composer = MCPServerComposer(
    composed_server_name="dev-environment",
    conflict_resolution=ConflictResolution.PREFIX
)

# Compose development-focused servers
dev_server = composer.compose_from_pyproject(
    include_servers=[
        "code-review-mcp-server",
        "documentation-mcp-server", 
        "testing-mcp-server"
    ]
)

# Access all development tools in one place
print("Available tools:", composer.list_tools())

Custom Integration

from mcp_server_composer import MCPServerComposer
from my_custom_server import MyMCPServer

# Create composer
composer = MCPServerComposer()

# Compose discovered servers
unified_server = composer.compose_from_pyproject()

# Add your custom server manually if needed
composer.add_server("custom", MyMCPServer())

# Get final composition summary
summary = composer.get_composition_summary()
print(f"Final server has {summary['total_tools']} tools from {summary['source_servers']} sources")

Project Structure

When using MCP Server Composer, structure your project like this:

my-project/
├── pyproject.toml          # Define MCP server dependencies
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py         # Use composed server
├── composed_server.py      # Generated unified server (optional)
└── README.md

Sample pyproject.toml

[project]
name = "my-data-project"
dependencies = [
    "jupyter-mcp-server>=1.0.0",
    "earthdata-mcp-server>=0.1.0",
    "fastmcp>=1.2.0"
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "mcp-server-composer>=1.0.0"
]

Error Handling

The library provides comprehensive error handling:

from mcp_server_composer import MCPServerComposer, MCPComposerError, MCPDiscoveryError

try:
    composer = MCPServerComposer()
    server = composer.compose_from_pyproject()
except MCPDiscoveryError as e:
    print(f"Discovery failed: {e}")
    print(f"Search paths: {e.search_paths}")
except MCPComposerError as e:
    print(f"Composition failed: {e}")
    print(f"Server count: {e.server_count}")

Troubleshooting

Common Issues

No MCP servers found: Ensure your dependencies include packages with "mcp" in the name
Import errors: Check that MCP server packages are properly installed
Naming conflicts: Use appropriate conflict resolution strategy
Missing tools: Verify that server packages export an app variable

Debug Mode

# Enable verbose logging
python -m mcp_server_composer discover --verbose

# Check specific package
python -c "
from mcp_server_composer import MCPServerDiscovery
discovery = MCPServerDiscovery()
result = discovery._analyze_mcp_server('your-package-name')
print(result)
"


## API Reference

### MCPServerComposer

Main class for composing MCP servers:

```python
MCPServerComposer(
    composed_server_name: str = "composed-mcp-server",
    conflict_resolution: ConflictResolution = ConflictResolution.PREFIX
)

Methods:

compose_from_pyproject(pyproject_path, include_servers, exclude_servers) - Compose servers from dependencies
get_composition_summary() - Get summary of composition results
list_tools() - List all available tools
list_prompts() - List all available prompts
get_source_info() - Get mapping of tools/prompts to source servers

MCPServerDiscovery

Class for discovering MCP servers:

MCPServerDiscovery(mcp_server_patterns: List[str] = None)

Methods:

discover_from_pyproject(pyproject_path) - Discover servers from pyproject.toml
get_package_version(dependency_spec) - Extract version from dependency string

ConflictResolution

Enum for conflict resolution strategies:

PREFIX - Add server name as prefix
SUFFIX - Add server name as suffix
OVERRIDE - Last server wins
IGNORE - Skip conflicting items
ERROR - Raise error on conflicts

Requirements

Python 3.8+
FastMCP >= 1.2.0
TOML parsing support

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes and add tests
Ensure all tests pass (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for version history and changes.

Support

📖 Documentation: Full API documentation and examples in this README
🐛 Issues: Report bugs and request features on GitHub Issues
💬 Discussions: Join the conversation in GitHub Discussions

Related Projects

FastMCP - Python SDK for Model Context Protocol
MCP Specification - Official MCP specification
Jupyter MCP Server - MCP server for Jupyter functionality
Earthdata MCP Server - MCP server for NASA Earthdata access

Made with ❤️ by the Datalayer team

Earthdata MCP Server - MCP server for NASA Earthdata

Changelog

See CHANGELOG.md for a detailed history of changes.

Support

GitHub Issues: Report bugs or request features
Documentation: Full documentation
Community: Join the discussion

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
mcp_server_composer		mcp_server_composer
tests		tests
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml

Uh oh!

datalayer/mcp-server-composer

Folders and files

Latest commit

History

Repository files navigation

MCP Server Composer

Overview

Features

Installation

Quick Start

Using the Library

Using the CLI

Detailed Usage

CLI Commands

discover - Find MCP Servers

compose - Create Unified Server

Programmatic Usage

Basic Composition

Advanced Configuration

Discovery Only

Configuration

Conflict Resolution Strategies

Example Conflict Resolution

Real-World Examples

Data Science Workflow

Development Environment

Custom Integration

Project Structure

Sample pyproject.toml

Error Handling

Troubleshooting

Common Issues

Debug Mode

MCPServerDiscovery

ConflictResolution

Requirements

Contributing

License

Changelog

Support

Related Projects

Changelog

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

`discover` - Find MCP Servers

`compose` - Create Unified Server

Packages