Skip to main content
Glama

Shannon MCP

by krzemienski
OverviewInspectNewSchemaRelated ServersScore
Python
Remote
2
  • Linux
  • Apple

Shannon MCP Server

Python Version License MCP Protocol Build Status Coverage

A comprehensive Model Context Protocol (MCP) server for Claude Code, built using an innovative 26-agent collaborative AI system.

Shannon MCP provides programmatic control over Claude Code CLI operations through a standardized MCP interface, enabling seamless integration with Claude Desktop and other MCP clients.

Key Features

  • 7 MCP Tools: Complete Claude Code session management and control

  • 3 MCP Resources: Real-time access to configuration, agents, and sessions

  • 26 Specialized AI Agents: Multi-agent system for complex task handling

  • Production-Ready: 95% complete, ~28K lines of code, 64 comprehensive test files

  • Advanced Features: Checkpoints, Hooks, Analytics, and Process Registry

Table of Contents

Overview

What is Shannon MCP Server?

Shannon MCP Server is a comprehensive Model Context Protocol (MCP) implementation that brings the power of Claude Code to any MCP-compatible client. It exposes Claude Code's capabilities through a standardized interface, enabling:

  • Programmatic Session Management: Create, monitor, and control Claude Code sessions via API

  • Real-time Streaming: JSONL streaming with backpressure handling for live output

  • Advanced Version Control: Git-like checkpoints for session state management

  • Event-Driven Automation: Hooks framework for automated workflows

  • Usage Analytics: Comprehensive tracking and reporting of all operations

  • Multi-Agent Collaboration: 26 specialized agents for complex task handling

Why Shannon MCP?

Shannon MCP Server differentiates itself through:

  1. Comprehensive Implementation: Full Claude Code feature parity with extensive test coverage

  2. Production-Ready Architecture: Built with enterprise-grade reliability and performance

  3. Multi-Agent Innovation: First MCP server built entirely by collaborative AI agents

  4. Extensible Design: Plugin system, hooks framework, and custom agent support

  5. Developer-First: Rich documentation, examples, and interactive testing tools

Key Differentiators

  • 26-Agent System: Specialized agents handle everything from architecture to deployment

  • Content-Addressable Storage: Efficient deduplication and compression for checkpoints

  • Bidirectional Streaming: Real-time JSONL parsing with error recovery

  • Process Registry: System-wide session tracking and resource monitoring

  • Zero-Downtime Updates: Hot-reload configuration and graceful shutdowns

Features

Core Features

Binary Management

  • Automatic Discovery: Finds Claude Code installations across system PATH, NVM, and standard locations

  • Version Detection: Validates compatibility and tracks version information

  • Intelligent Caching: Reduces discovery overhead with smart cache invalidation

  • Fallback Strategies: Multiple search methods ensure reliable binary location

Session Orchestration

  • Full Lifecycle Management: Create, start, monitor, pause, resume, and terminate sessions

  • Concurrent Sessions: Handle multiple simultaneous Claude Code sessions

  • Real-time Streaming: JSONL event stream with bidirectional communication

  • Resource Tracking: Monitor memory, CPU, and I/O usage per session

  • Graceful Cleanup: Automatic resource cleanup on session termination

JSONL Streaming

  • Backpressure Handling: Prevents memory overflow during high-volume streaming

  • Error Recovery: Automatic retry and reconnection logic

  • Message Buffering: Configurable buffer sizes for optimal throughput

  • Protocol Validation: Ensures MCP protocol compliance

Advanced Features

Checkpoint System

  • Git-like Versioning: Create, restore, and manage session snapshots

  • Content-Addressable Storage (CAS): SHA-256 based deduplication saves storage space

  • Compression: Zstandard compression reduces checkpoint size by up to 90%

  • Diff Generation: Compare checkpoints to track changes over time

  • Timeline Management: Navigate checkpoint history with branching support

  • Automatic Pruning: Configurable retention policies for storage management

Hooks Framework

  • Event-Driven Automation: Trigger commands on Claude Code events

  • Multiple Hook Types: PreToolUse, PostToolUse, Notification, Stop, SubagentStop, UserPromptSubmit

  • Flexible Configuration: Project-level, user-level, and global scopes

  • Environment Variables: Rich context passed to hook commands

  • Sandboxed Execution: Optional isolation for security

Analytics Engine

  • Usage Tracking: Record all sessions, tool calls, and resource usage

  • Cost Monitoring: Track token usage and estimate costs per session

  • Performance Metrics: Latency, throughput, and error rates

  • Export Capabilities: CSV and JSON export for external analysis

  • Retention Policies: Automatic cleanup of old analytics data

Multi-Agent System

26 Specialized Agents

Core Architecture Agents (4)

  • Architecture Agent: System design and component relationships

  • Claude Code SDK Expert: Deep CLI integration knowledge

  • Python MCP Server Expert: MCP protocol implementation

  • Functional MCP Server Agent: Business logic and workflows

Infrastructure Agents (7)

  • Database Storage Agent: SQLite optimization and CAS

  • Streaming Concurrency Agent: Async patterns and backpressure

  • JSONL Streaming Agent: Real-time parsing and buffering

  • Process Management Agent: System process monitoring

  • Filesystem Monitor Agent: Real-time change detection

  • Platform Compatibility Agent: Cross-platform support

  • Storage Algorithms Agent: Compression and deduplication

Quality & Security Agents (6)

  • Security Validation Agent: Input validation and injection prevention

  • Testing Quality Agent: Comprehensive test coverage

  • Error Handling Agent: Robust error recovery

  • Performance Optimizer Agent: Profiling and optimization

  • Documentation Agent: API docs and examples

  • DevOps Deployment Agent: CI/CD and automation

Specialized Agents (9)

  • Telemetry OpenTelemetry Agent: Observability implementation

  • Analytics Monitoring Agent: Usage analytics and reporting

  • Integration Specialist Agent: Third-party integrations

  • Project Coordinator Agent: Task management

  • Migration Specialist Agent: Database migrations

  • SSE Transport Agent: Server-Sent Events

  • Resources Specialist Agent: MCP resource exposure

  • Prompts Engineer Agent: Prompt templates

  • Plugin Architect Agent: Extension system

Infrastructure

Process Registry

  • System-Wide Tracking: Monitor all Shannon MCP instances across the system

  • Resource Discovery: Find and connect to existing sessions

  • Cleanup Automation: Remove stale process entries

  • Health Monitoring: Track process health and resource usage

Caching System

  • Multi-Layer Caching: Binary, session, and configuration caches

  • Smart Invalidation: Automatic cache refresh on changes

  • Configurable TTL: Customizable time-to-live per cache type

  • Memory Limits: Prevent unbounded cache growth

Transport Layer

  • STDIO Transport: Standard input/output for MCP communication

  • SSE Transport: Server-Sent Events for web integration (future)

  • Protocol Negotiation: Automatic protocol version detection

  • Message Validation: Strict JSON-RPC compliance

Architecture

High-Level System Architecture

┌─────────────────────────────────────────────────────────────────────┐ │ MCP CLIENT LAYER │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Claude │ │ MCP │ │ Custom │ │ │ │ Desktop │ │ Inspector │ │ Client │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ └──────────────────┴──────────────────┘ │ │ │ │ │ JSON-RPC over STDIO │ └────────────────────────────┼──────────────────────────────────────────┘ │ ┌────────────────────────────┼──────────────────────────────────────────┐ │ SHANNON MCP SERVER │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ MCP Protocol Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Tools │ │ Resources │ │ Prompts │ │ │ │ │ │ (7) │ │ (3) │ │ (Future) │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Core Managers Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Binary │ │ Session │ │ Agent │ │ │ │ │ │ Manager │ │ Manager │ │ Manager │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Advanced Features Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Checkpoint │ │ Hooks │ │ Analytics │ │ │ │ │ │ System │ │ Framework │ │ Engine │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Infrastructure Layer │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Streaming │ │ Storage │ │ Process │ │ │ │ │ │ (JSONL) │ │ (SQLite) │ │ Registry │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────────┘ │ ┌────────────────────────────┼──────────────────────────────────────────┐ │ CLAUDE CODE CLI │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Claude Code Binary │ │ │ │ - File operations │ │ │ │ - Shell commands │ │ │ │ - Code generation │ │ │ │ - Interactive workflows │ │ │ └──────────────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────────┘

Component Relationships

Session Manager ──┬──> Binary Manager (discovers Claude Code) │ ├──> Streaming Processor (handles JSONL output) │ ├──> Checkpoint Manager (saves/restores state) │ ├──> Hooks Manager (triggers automation) │ └──> Analytics Engine (tracks usage) Agent Manager ────┬──> Agent Registry (26 specialized agents) │ ├──> Task Dispatcher (assigns work) │ └──> Result Aggregator (combines outputs) Checkpoint System ┬──> CAS Storage (content-addressable storage) │ ├──> Timeline Manager (version graph) │ └──> Diff Engine (change detection) Process Registry ─┬──> System Monitor (process tracking) │ ├──> Health Checker (status monitoring) │ └──> Cleanup Service (garbage collection)

Data Flow

1. Client Request └──> MCP Protocol Layer (validate JSON-RPC) └──> Tool Handler (route to appropriate manager) └──> Manager (execute operation) └──> Claude Code Binary (perform work) └──> JSONL Stream (output events) └──> Stream Processor (parse and buffer) └──> Response Builder (format MCP response) └──> Client (receive result) 2. Session Lifecycle Create ──> Start ──> Execute ──> Monitor ──> Complete ──> Cleanup │ │ │ │ │ │ └─> DB ──┴─> Binary ┴─> Stream ─┴─> Hooks ──┴─> Analytics┴─> Registry

Quick Start

Get started with Shannon MCP in 5 commands:

# 1. Clone the repository git clone https://github.com/krzemienski/shannon-mcp.git cd shannon-mcp # 2. Install dependencies with Poetry poetry install # 3. Activate the virtual environment poetry shell # 4. Verify installation shannon-mcp --help # 5. Run the server (starts in stdio mode for MCP communication) shannon-mcp

That's it! The server is now ready to accept MCP protocol commands.

Quick Test

Test the server with a simple MCP request:

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | shannon-mcp

Expected response:

{ "jsonrpc": "2.0", "result": { "protocolVersion": "2024-11-05", "capabilities": { "tools": {}, "resources": {} }, "serverInfo": { "name": "shannon-mcp", "version": "0.1.0" } }, "id": 1 }

Installation

For detailed installation instructions, see INSTALLATION.md.

Prerequisites

  • Python 3.11+

  • Poetry (Python package manager)

  • Claude Code CLI (the binary this server manages)

  • Git

  • 100MB disk space minimum, 500MB recommended

Quick Installation

# Install from source (recommended for development) git clone https://github.com/krzemienski/shannon-mcp.git cd shannon-mcp poetry install # Verify installation poetry shell shannon-mcp --version

Install with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{ "mcpServers": { "shannon-mcp": { "command": "shannon-mcp", "args": [], "env": { "SHANNON_CONFIG_PATH": "/home/user/.shannon-mcp/config.yaml" } } } }

For PyPI installation (when available):

pip install shannon-mcp

See INSTALLATION.md for:

  • Detailed prerequisites and system requirements

  • Configuration options and environment variables

  • Troubleshooting common installation issues

  • Upgrading and uninstallation procedures

Usage

For comprehensive usage documentation, see USAGE.md.

MCP Tools (7)

Shannon MCP exposes 7 powerful tools through the MCP protocol:

  1. find_claude_binary - Automatically discover Claude Code installation

  2. create_session - Start a new Claude Code session with a prompt

  3. send_message - Send follow-up messages to active sessions

  4. cancel_session - Stop a running session immediately

  5. list_sessions - View all sessions (active, completed, failed)

  6. list_agents - Browse the 26 specialized AI agents

  7. assign_task - Delegate tasks to the most appropriate agent

MCP Resources (3)

Access read-only system state through resources:

  1. shannon://config - Current configuration settings

  2. shannon://agents - Detailed agent information

  3. shannon://sessions - Active session data and statistics

Basic Usage Examples

Create a Session

# Using Python MCP client session = await client.call_tool("create_session", { "prompt": "Create a FastAPI REST API with user authentication", "model": "claude-3-sonnet" }) print(f"Session ID: {session['session_id']}")

List Active Sessions

sessions = await client.call_tool("list_sessions", { "state": "running" }) print(f"Active sessions: {len(sessions)}")

Assign Task to Agent

assignment = await client.call_tool("assign_task", { "description": "Optimize database queries for better performance", "required_capabilities": ["database", "performance", "sql"], "priority": "high" }) print(f"Assigned to: {assignment['agent_name']}")

See USAGE.md for:

  • Complete tool and resource documentation

  • Advanced features (checkpoints, hooks, analytics)

  • Multi-agent collaboration patterns

  • Best practices and examples

  • Error handling and debugging

Documentation

Shannon MCP includes comprehensive documentation for all aspects of the system:

User Documentation

  • INSTALLATION.md - Complete installation guide with troubleshooting

  • USAGE.md - User guide with examples and best practices

  • TESTING.md - Testing guide for developers and contributors

  • DEPLOYMENT.md - Deployment guide for production environments (future)

Technical Specification

API Documentation

  • API Reference - OpenAPI specification and SDK docs (future)

  • Examples - Code examples and recipes (see USAGE.md)

  • Architecture Diagrams - System architecture and data flow

Project Status

Multi-Agent System

Shannon MCP is built using an innovative 26-agent collaborative system, where specialized AI agents work together to implement the entire MCP server.

How It Works

┌─────────────────────────────────────────────────────────────────┐ │ ORCHESTRATION LAYER │ │ ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ Build │ │ Agent │ │ Shared │ │ │ │ Orchestrator │ │ Progress │ │ Memory │ │ │ └────────┬────────┘ └──────┬───────┘ └────────┬────────┘ │ │ └───────────────────┴────────────────────┘ │ └───────────────────────────────┼─────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ Core Architecture Infrastructure Specialized Agents (4) Agents (7) Agents (9)

Agent Categories

Core Architecture (4 agents)

  • System design and architectural decisions

  • Claude Code SDK deep integration

  • MCP protocol implementation

  • Business logic and workflows

Infrastructure (7 agents)

  • Database storage and optimization

  • Streaming and concurrency patterns

  • JSONL parsing and buffering

  • Process and filesystem monitoring

  • Platform compatibility

  • Storage algorithms

Quality & Security (6 agents)

  • Security validation and hardening

  • Comprehensive testing

  • Error handling and recovery

  • Performance optimization

  • Documentation generation

  • DevOps and deployment

Specialized (9 agents)

  • Telemetry and observability

  • Analytics and monitoring

  • Third-party integrations

  • Project coordination

  • Database migrations

  • SSE transport

  • Resource exposure

  • Prompt engineering

  • Plugin architecture

Collaboration Mechanisms

  1. Shared Memory: Agents share knowledge through a persistent context store

  2. Task Distribution: Orchestrator assigns tasks based on agent expertise

  3. Progress Tracking: Real-time monitoring of all agent activities

  4. Cross-Agent Review: Agents review each other's work for quality

  5. Knowledge Evolution: Patterns and solutions improve over time

Orchestrator Commands

# Initialize the build process /mcp-build-orchestrator init --project-path ~/shannon-mcp # Monitor agent progress /mcp-agent-progress status --detailed # View shared memory /mcp-shared-memory status # Check agent context /mcp-agent-context view --agent-name "Architecture Agent"

Benefits of Multi-Agent Development

  • Specialized Expertise: Each agent focuses on specific domains

  • Parallel Development: Multiple components built simultaneously

  • Consistent Quality: Cross-agent reviews ensure high standards

  • Knowledge Retention: Shared memory preserves patterns and solutions

  • Rapid Iteration: Agents learn and improve continuously

Development

Setting Up Development Environment

# Clone the repository git clone https://github.com/krzemienski/shannon-mcp.git cd shannon-mcp # Install dependencies (including dev tools) poetry install # Activate virtual environment poetry shell # Install pre-commit hooks (optional) pre-commit install # Run tests to verify setup pytest

Project Structure

shannon-mcp/ ├── src/shannon_mcp/ # Source code (~28K lines) │ ├── managers/ # Core managers (Binary, Session, Agent) │ ├── storage/ # Database and CAS │ ├── streaming/ # JSONL streaming │ ├── checkpoint/ # Checkpoint system │ ├── hooks/ # Hooks framework │ ├── analytics/ # Analytics engine │ ├── registry/ # Process registry │ ├── mcp/ # MCP protocol implementation │ ├── utils/ # Utilities │ └── server.py # Main server entry point ├── tests/ # Test suite (64 files, ~10.5K lines) │ ├── functional/ # Complete component tests (20 files) │ ├── benchmarks/ # Performance tests (13 files) │ ├── mcp-integration/ # MCP protocol tests │ ├── utils/ # Test utilities │ └── conftest.py # Shared fixtures ├── docs/ # Technical specifications ├── pyproject.toml # Poetry configuration ├── INSTALLATION.md # Installation guide ├── USAGE.md # User guide ├── TESTING.md # Testing guide └── README.md # This file

Development Workflow

1. Code Style

Shannon MCP uses strict code quality tools:

# Format code with black black src/ tests/ # Sort imports with isort isort src/ tests/ # Lint with flake8 flake8 src/ tests/ # Type check with mypy mypy src/ # Run all checks poetry run pre-commit run --all-files

2. Running Tests

# Run all tests pytest # Run with coverage pytest --cov=shannon_mcp --cov-report=html # Run specific test category pytest tests/functional/ # Functional tests pytest tests/benchmarks/ # Performance tests pytest -m integration # Integration tests # Run fast tests only pytest -m "not slow" # Stop on first failure pytest -x # Show detailed output pytest -v -s

3. Making Changes

# Create a feature branch git checkout -b feature/my-feature # Make changes and add tests # ... # Run tests pytest # Check code quality pre-commit run --all-files # Commit changes git add . git commit -m "feat: add new feature" # Push and create PR git push origin feature/my-feature

Contributing Guidelines

We welcome contributions! Here's how to get started:

  1. Fork the repository and clone your fork

  2. Create a feature branch from main

  3. Make your changes with tests

  4. Run the test suite to ensure everything works

  5. Follow code style guidelines (black, flake8, mypy)

  6. Write clear commit messages following conventional commits

  7. Submit a pull request with a detailed description

Commit Message Format:

<type>(<scope>): <subject> <body> <footer>

Types: feat, fix, docs, test, refactor, perf, chore

Example:

feat(session): add timeout configuration for sessions - Add timeout parameter to session creation - Implement timeout handling in session manager - Add tests for timeout behavior Closes #123

Project Status

Current Version: 0.1.0

Implementation Status: 95% Complete

Completed Components ✓

  • ✅ Core Infrastructure (100%)

    • MCP protocol implementation

    • Binary manager with auto-discovery

    • Session manager with streaming

    • JSONL stream processor

  • ✅ Advanced Features (95%)

    • Checkpoint system with CAS

    • Hooks framework

    • Agent system

    • Analytics engine

  • ✅ Infrastructure (90%)

    • Process registry

    • Storage layer (SQLite + CAS)

    • Caching system

    • Error handling

  • ✅ Testing (80%+ coverage)

    • 64 test files

    • ~10.5K lines of test code

    • Unit, functional, integration, and benchmark tests

  • ✅ Documentation (100%)

    • Installation guide

    • User guide

    • Testing guide

    • Technical specifications

In Progress / Remaining 5%

  • 🔄 SSE Transport - Server-Sent Events for web integration

  • 🔄 Plugin System - Dynamic plugin loading

  • 🔄 API Documentation - OpenAPI specification

  • 🔄 Deployment Guide - Production deployment documentation

  • 🔄 Performance Tuning - Final optimizations

Roadmap

Q1 2025

  • Complete SSE transport implementation

  • Publish to PyPI

  • API documentation generation

  • Performance optimization

Q2 2025

  • Plugin system MVP

  • Cloud integration features

  • Enterprise authentication

  • Advanced analytics dashboard

Q3 2025

  • Web UI for management

  • Multi-user support

  • Team collaboration features

  • Advanced security features

Code Metrics

  • Source Code: 61 Python files, ~28,000 lines

  • Test Code: 64 test files, ~10,500 lines

  • Test Coverage: 80%+ overall, 90%+ for critical components

  • Dependencies: 19 production, 11 development

  • Documentation: 4 comprehensive guides + technical specs

Requirements

System Requirements

  • Operating System: Linux, macOS, or Windows (WSL recommended for Windows)

  • Python: 3.11 or higher

  • Disk Space: 100MB minimum, 500MB recommended for data storage

  • RAM: 512MB minimum, 1GB recommended

  • Network: Internet connection for initial setup and package downloads

Software Dependencies

Required

  • Poetry (>=1.5.0) - Python package manager

  • Git - Version control

  • Claude Code CLI - The binary that Shannon MCP manages

Optional

  • Docker - For containerized deployment

  • PostgreSQL - Alternative to SQLite for production (future)

  • Redis - For distributed caching (future)

Python Dependencies

Production Dependencies (19)

Core & MCP

  • mcp (^1.0.0) - Model Context Protocol SDK

  • aiosqlite (^0.19.0) - Async SQLite driver

  • aiofiles (^23.0.0) - Async file I/O

  • aiohttp (^3.9.0) - Async HTTP client

Streaming & Processing

  • watchdog (^4.0.0) - File system monitoring

  • json-stream (^2.3.0) - Streaming JSON parser

  • zstandard (^0.22.0) - High-performance compression

CLI & Configuration

  • click (^8.1.0) - CLI framework

  • pyyaml (^6.0.0) - YAML config parsing

  • python-dotenv (^1.0.0) - Environment variables

  • toml (^0.10.2) - TOML config parsing

Data & Validation

  • pydantic (^2.0.0) - Data validation

  • rich (^13.0.0) - Terminal formatting

Utilities

  • httpx (^0.27.0) - Modern HTTP client

  • psutil (^5.9.0) - Process monitoring

  • semantic-version (^2.10.0) - Version comparison

  • packaging (^24.0) - Version utilities

Monitoring

  • structlog (^24.0.0) - Structured logging

  • sentry-sdk (^2.0.0) - Error tracking

Development Dependencies (11)

Testing

  • pytest (^7.4.0) - Testing framework

  • pytest-asyncio (^0.21.0) - Async test support

  • pytest-cov (^4.1.0) - Coverage reporting

  • pytest-mock (^3.12.0) - Mocking utilities

  • pytest-benchmark (^4.0.0) - Performance benchmarks

Code Quality

  • black (^23.0.0) - Code formatter

  • flake8 (^6.0.0) - Linter

  • mypy (^1.5.0) - Type checker

  • isort (^5.13.0) - Import sorter

Development Tools

  • pre-commit (^3.3.0) - Git hooks

  • ipython - Interactive shell (optional)

Testing

For comprehensive testing documentation, see TESTING.md.

Test Suite Overview

  • 64 test files with ~10,500 lines of test code

  • 80%+ overall coverage, 90%+ for critical components

  • 4 test categories: Unit, Functional, Integration, Benchmark

Quick Test Commands

# Run all tests poetry run pytest # Run with coverage report poetry run pytest --cov=shannon_mcp --cov-report=html # Run specific test categories poetry run pytest tests/functional/ # Functional tests poetry run pytest tests/benchmarks/ # Performance tests poetry run pytest -m integration # Integration tests poetry run pytest -m "not slow" # Fast tests only # Run specific component tests poetry run pytest tests/test_binary_manager.py # Binary manager poetry run pytest tests/test_session_manager.py # Session manager poetry run pytest tests/test_streaming.py # Streaming # Debug failing tests poetry run pytest -v -s --pdb -x # Stop on first failure

Test Categories

Unit Tests (root level) - Fast, isolated tests for individual functions Functional Tests (20 files) - Complete component testing with all features Integration Tests - End-to-end workflows with real MCP protocol Benchmark Tests (13 files) - Performance testing and regression detection

Coverage Reports

# Generate HTML coverage report poetry run pytest --cov=shannon_mcp --cov-report=html open htmlcov/index.html # Terminal report with missing lines poetry run pytest --cov=shannon_mcp --cov-report=term-missing # XML report for CI/CD poetry run pytest --cov=shannon_mcp --cov-report=xml

Continuous Integration

Shannon MCP uses GitHub Actions for CI/CD:

  • Test Matrix: Python 3.11, 3.12 on Ubuntu, macOS

  • Quality Checks: black, flake8, mypy, isort

  • Coverage Enforcement: Fails if coverage drops below 80%

  • Performance Regression: Benchmark comparisons against baseline

See TESTING.md for:

  • Complete test documentation

  • Writing new tests

  • Debugging test failures

  • Performance benchmarking

  • Manual testing with MCP Inspector

Deployment

Development Deployment

# Run locally with Poetry poetry run shannon-mcp # Run with debug logging SHANNON_LOG_LEVEL=DEBUG poetry run shannon-mcp # Run with custom config SHANNON_CONFIG_PATH=/path/to/config.yaml poetry run shannon-mcp

Production Deployment

Coming Soon: Full production deployment guide

For now, see configuration options in INSTALLATION.md.

Docker Deployment (Future)

# Build Docker image docker build -t shannon-mcp:latest . # Run container docker run -d \ -v ~/.shannon-mcp:/root/.shannon-mcp \ -e SHANNON_LOG_LEVEL=INFO \ shannon-mcp:latest

Configuration

Default configuration location: ~/.shannon-mcp/config.yaml

Key configuration sections:

  • binary_discovery: Claude Code search paths

  • storage: Database and cache settings

  • sessions: Session limits and timeouts

  • logging: Log levels and output

  • analytics: Usage tracking settings

  • hooks: Automation configuration

  • performance: Worker threads and buffers

See INSTALLATION.md for complete configuration reference.

License

Shannon MCP Server is licensed under the MIT License.

MIT License Copyright (c) 2025 Shannon MCP Team Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See the LICENSE file for full details.

Acknowledgments

Shannon MCP Server is built on the shoulders of giants and innovative technologies:

Technologies

Community

  • Anthropic for creating Claude Code and the MCP protocol

  • MCP Community for protocol improvements and feedback

  • Open Source Contributors for dependencies and tools

  • Early Adopters for testing and feature requests

Innovation

This project demonstrates a groundbreaking approach to software development:

Multi-Agent Collaborative AI Development - Shannon MCP is the first MCP server built entirely by 26 specialized AI agents working together through orchestration systems, shared memory, and collaborative workflows. This represents the future of software development where AI agents handle everything from architecture to deployment.

Built With

  • 🤖 26 Specialized AI Agents - Core architecture, infrastructure, quality, and specialized domain experts

  • 🧠 Shared Memory System - Knowledge graph enabling agent collaboration

  • 🎯 Task Orchestration - Intelligent work distribution based on agent expertise

  • 📊 Progress Tracking - Real-time monitoring of all agent activities

  • 🔄 Iterative Refinement - Cross-agent reviews and continuous improvement

Support

Getting Help

Reporting Issues

When reporting issues, please include:

  1. Environment Details: OS, Python version, Shannon MCP version

  2. Steps to Reproduce: Minimal reproducible example

  3. Expected Behavior: What you expected to happen

  4. Actual Behavior: What actually happened

  5. Logs: Relevant log output (use SHANNON_LOG_LEVEL=DEBUG)

Feature Requests

We welcome feature requests! Please include:

  1. Use Case: What problem does this solve?

  2. Proposed Solution: How would you like it to work?

  3. Alternatives: What alternatives have you considered?

  4. Additional Context: Any other relevant information

Community

Security

For security vulnerabilities, please email [security email] instead of creating a public issue. We take security seriously and will respond promptly.

Links

Shannon MCP Server - Empowering developers with programmatic Claude Code control

Built by 26 AI agents working collaboratively

Install • Documentation • GitHub

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Related Resources

Related MCP Servers

  • Linear MCP Server

    cpropster
    -
    security
    A
    license
    -
    quality
    A Model Context Protocol server that allows Claude to interact with Linear's API for managing teams, issues, projects, and cycles.
    Last updated -
    2,578
    2
    MIT License

  • Claude Code MCP

    auchenberg
    A
    security
    A
    license
    A
    quality
    An implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.
    Last updated -
    8
    401
    177
    MIT License

  • my-mcp-server

    15972289829
    A
    security
    F
    license
    A
    quality
    A Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.
    Last updated -
    30
    • Apple

  • MCP Server for Unity

    zabaglione
    A
    security
    A
    license
    A
    quality
    A Model Context Protocol server that enables Claude to interact directly with Unity projects, providing tools for script creation, asset management, and project building.
    Last updated -
    15
    7
    MIT License
    • Linux
    • Apple

View all related MCP servers

Appeared in Searches

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/krzemienski/shannon-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server