# mcp-orchestration
MCP server orchestration and management tools
## Overview
**mcp-orchestration** is a Model Context Protocol (MCP) server that provides centralized configuration management and orchestration for MCP client applications. It enables cryptographically signed, content-addressable storage of client configurations with automated diff detection and update recommendations.
This project follows the MCP specification and can be integrated with:
- Claude Desktop
- Cursor
- Other MCP-compatible clients
## Features
- **Cryptographic Signatures** - Ed25519 signatures for configuration integrity and authenticity
- **Content-Addressable Storage** - SHA-256 based artifact identification for immutable configs
- **Multi-Client Registry** - Support for multiple MCP clients (Claude Desktop, Cursor) with profile-based configs
- **Configuration Diff** - Intelligent comparison with field-level change detection
- **MCP Tools & Resources** - 4 tools (list_clients, list_profiles, get_config, diff_config) and 2 resources
- **CLI Initialization** - Quick-start command to generate signed sample configurations
- **Comprehensive Testing** - 67 passing tests with full integration coverage
## Installation
### From PyPI (Recommended)
```bash
pip install mcp-orchestration
```
### From Source
```bash
# Clone repository
git clone https://github.com/liminalcommons/mcp-orchestration.git
cd mcp-orchestration
# Install with development dependencies
pip install -e ".[dev]"
# Install pre-commit hooks (for contributors)
pre-commit install
```
### Initialize Configuration Storage
After installation, generate signed sample configurations:
```bash
mcp-orchestration-init
```
This creates:
- Ed25519 signing keys at `~/.mcp-orchestration/keys/`
- Sample configurations for supported clients
- Content-addressable artifact storage
## Configuration
### Environment Variables
Create a `.env` file:
```env
# Application configuration
MCP_ORCHESTRATION_LOG_LEVEL=INFO
# Add your configuration here
```
### Client Configuration
#### Claude Desktop (macOS)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"mcp-orchestration": {
"command": "python3",
"args": ["-m", "mcp_orchestrator.mcp.server"],
"env": {
"PYTHONPATH": "/path/to/mcp-orchestration/src"
}
}
}
}
```
For installed package (after PyPI release):
```json
{
"mcpServers": {
"mcp-orchestration": {
"command": "mcp-orchestration"
}
}
}
```
#### Cursor IDE
Add to Cursor settings JSON:
```json
{
"mcp": {
"servers": {
"mcp-orchestration": {
"command": "python3",
"args": ["-m", "mcp_orchestrator.mcp.server"]
}
}
}
}
```
## Usage
Once configured in your MCP client (Claude Desktop, Cursor, etc.), the following tools are available:
### MCP Tools
**list_clients** - List all supported MCP client families:
```
Returns: client_id, display_name, platform, capabilities, profiles
```
**list_profiles** - List profiles for a specific client:
```
Input: client_id (e.g., "claude-desktop")
Returns: profile_id, display_name, artifact_id, signature
```
**get_config** - Retrieve a signed configuration artifact:
```
Input: client_id, profile_id (default: "default"), artifact_id (optional)
Returns: Full signed artifact with payload, signature, metadata
```
**diff_config** - Compare local config against stored version:
```
Input: client_id, profile_id, local_payload
Returns: Diff status (up-to-date/outdated/diverged), changes, recommendation
```
### CLI Commands
```bash
# Initialize configuration storage with sample configs
mcp-orchestration-init
# Initialize to custom location
mcp-orchestration-init --storage-path /custom/path
# Regenerate existing configurations
mcp-orchestration-init --regenerate
```
## Development
### Quick Reference
**Discover all available commands:**
```bash
just --list
```
**Common tasks:**
```bash
just test # Run test suite
just lint # Check code style
just pre-merge # Run all checks (required before PR)
just build # Build distribution packages
just help # Show common workflows
```
The [justfile](justfile) is self-documenting - run `just` or `just --list` to see all commands.
### Common Workflows
**Running tests:**
```bash
just test # Full test suite
just smoke # Quick smoke tests (~10 sec)
just test-coverage # With coverage report
```
**Code quality:**
```bash
just lint # Check style
just lint-fix # Auto-fix issues
just format # Format code
just typecheck # Type checking
just check # All quality checks
```
**Before creating PR:**
```bash
just pre-merge # Run lint + test + coverage (required)
```
**Building & releasing:**
```bash
just build # Build distribution packages
just prepare-release patch # Bump version, update CHANGELOG
just publish-test # Publish to TestPyPI
just publish-prod # Publish to PyPI
```
**Application:**
```bash
just run # Start the application
mcp-orchestration # Or run directly
```
### Without `just` (Fallback)
If `just` installation fails, use commands directly:
| Task | Command |
|------|---------|
| Run tests | `pytest` |
| Build | `./scripts/build-dist.sh` |
| Lint | `ruff check src/mcp_orchestration tests` |
| Format | `black src/mcp_orchestration tests` |
| Pre-merge | `./scripts/pre-merge.sh` |
| Type check | `mypy src/mcp_orchestration` |
See [justfile](justfile) for complete command mappings.
## Documentation
This project follows the [Diátaxis framework](https://diataxis.fr/) with three documentation directories:
### For End Users (user-docs/)
Learn how to **use** mcp-orchestration:
- **[Getting Started Tutorial](user-docs/tutorials/01-getting-started.md)** - Learn the basics
- **[How-To Guides](user-docs/how-to/)** - Solve specific problems
- **[API Reference](user-docs/reference/)** - Look up specifications
- **[Explanations](user-docs/explanation/)** - Understand concepts
### For Project Planning (project-docs/)
Project roadmap and architecture decisions:
- **[ROADMAP.md](project-docs/ROADMAP.md)** - Long-term vision and milestones
- **[Release Notes](project-docs/releases/)** - Version history and changes
- **[Architecture Decisions](project-docs/decisions/)** - ADRs and design choices
### For Contributors (dev-docs/)
Learn how to **build** mcp-orchestration:
- **[CONTRIBUTING.md](dev-docs/CONTRIBUTING.md)** - Contribution guidelines
- **[DEVELOPMENT.md](dev-docs/DEVELOPMENT.md)** - Developer setup and architecture
- **[TROUBLESHOOTING.md](dev-docs/TROUBLESHOOTING.md)** - Common development issues
- **[Vision Documents](dev-docs/vision/)** - Strategic design guidance
### For AI Coding Agents
- **[AGENTS.md](AGENTS.md)** - Machine-readable instructions (OpenAI/Google standard)
**Documentation Standard:**
- **[DOCUMENTATION_STANDARD.md](DOCUMENTATION_STANDARD.md)** - Writing guidelines and templates
## Project Principles
This project follows best practices for:
- **Code Quality** - Linting (ruff), formatting (black), type checking (mypy)
- **Testing** - Comprehensive test suite with 85%+ coverage
- **Documentation** - Clear, up-to-date documentation following Diátaxis framework
- **Agentic Coding** - Machine-readable instructions, stateful memory for AI agents
## License
MIT License - see [LICENSE](LICENSE)
## Related Projects
- [chora-base](https://github.com/liminalcommons/chora-base) - Python project template
- [chora-composer](https://github.com/liminalcommons/chora-composer) - Configuration-driven artifact generation
- [chora-platform](https://github.com/liminalcommons/chora-platform) - Shared platform tooling
---
🤖 Generated with [chora-base](https://github.com/liminalcommons/chora-base) template
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-orchestration",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "configuration, cryptography, mcp, model-context-protocol, orchestration",
"author": null,
"author_email": "Victor Piper <victor@liminalcommons.org>",
"download_url": "https://files.pythonhosted.org/packages/94/0f/1fee9ccf9d5f040de27416c0a42e910fb71509a60b50643a10aafcf384fa/mcp_orchestration-0.1.5.tar.gz",
"platform": null,
"description": "# mcp-orchestration\n\nMCP server orchestration and management tools\n\n## Overview\n\n**mcp-orchestration** is a Model Context Protocol (MCP) server that provides centralized configuration management and orchestration for MCP client applications. It enables cryptographically signed, content-addressable storage of client configurations with automated diff detection and update recommendations.\n\nThis project follows the MCP specification and can be integrated with:\n- Claude Desktop\n- Cursor\n- Other MCP-compatible clients\n\n## Features\n\n- **Cryptographic Signatures** - Ed25519 signatures for configuration integrity and authenticity\n- **Content-Addressable Storage** - SHA-256 based artifact identification for immutable configs\n- **Multi-Client Registry** - Support for multiple MCP clients (Claude Desktop, Cursor) with profile-based configs\n- **Configuration Diff** - Intelligent comparison with field-level change detection\n- **MCP Tools & Resources** - 4 tools (list_clients, list_profiles, get_config, diff_config) and 2 resources\n- **CLI Initialization** - Quick-start command to generate signed sample configurations\n- **Comprehensive Testing** - 67 passing tests with full integration coverage\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install mcp-orchestration\n```\n\n### From Source\n\n```bash\n# Clone repository\ngit clone https://github.com/liminalcommons/mcp-orchestration.git\ncd mcp-orchestration\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks (for contributors)\npre-commit install\n```\n\n### Initialize Configuration Storage\n\nAfter installation, generate signed sample configurations:\n\n```bash\nmcp-orchestration-init\n```\n\nThis creates:\n- Ed25519 signing keys at `~/.mcp-orchestration/keys/`\n- Sample configurations for supported clients\n- Content-addressable artifact storage\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file:\n\n```env\n# Application configuration\nMCP_ORCHESTRATION_LOG_LEVEL=INFO\n\n# Add your configuration here\n```\n\n### Client Configuration\n\n#### Claude Desktop (macOS)\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-orchestration\": {\n \"command\": \"python3\",\n \"args\": [\"-m\", \"mcp_orchestrator.mcp.server\"],\n \"env\": {\n \"PYTHONPATH\": \"/path/to/mcp-orchestration/src\"\n }\n }\n }\n}\n```\n\nFor installed package (after PyPI release):\n```json\n{\n \"mcpServers\": {\n \"mcp-orchestration\": {\n \"command\": \"mcp-orchestration\"\n }\n }\n}\n```\n\n#### Cursor IDE\n\nAdd to Cursor settings JSON:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"mcp-orchestration\": {\n \"command\": \"python3\",\n \"args\": [\"-m\", \"mcp_orchestrator.mcp.server\"]\n }\n }\n }\n}\n```\n## Usage\n\nOnce configured in your MCP client (Claude Desktop, Cursor, etc.), the following tools are available:\n\n### MCP Tools\n\n**list_clients** - List all supported MCP client families:\n```\nReturns: client_id, display_name, platform, capabilities, profiles\n```\n\n**list_profiles** - List profiles for a specific client:\n```\nInput: client_id (e.g., \"claude-desktop\")\nReturns: profile_id, display_name, artifact_id, signature\n```\n\n**get_config** - Retrieve a signed configuration artifact:\n```\nInput: client_id, profile_id (default: \"default\"), artifact_id (optional)\nReturns: Full signed artifact with payload, signature, metadata\n```\n\n**diff_config** - Compare local config against stored version:\n```\nInput: client_id, profile_id, local_payload\nReturns: Diff status (up-to-date/outdated/diverged), changes, recommendation\n```\n\n### CLI Commands\n\n```bash\n# Initialize configuration storage with sample configs\nmcp-orchestration-init\n\n# Initialize to custom location\nmcp-orchestration-init --storage-path /custom/path\n\n# Regenerate existing configurations\nmcp-orchestration-init --regenerate\n```\n## Development\n\n### Quick Reference\n\n**Discover all available commands:**\n```bash\njust --list\n```\n\n**Common tasks:**\n```bash\njust test # Run test suite\njust lint # Check code style\njust pre-merge # Run all checks (required before PR)\njust build # Build distribution packages\njust help # Show common workflows\n```\n\nThe [justfile](justfile) is self-documenting - run `just` or `just --list` to see all commands.\n\n### Common Workflows\n\n**Running tests:**\n```bash\njust test # Full test suite\njust smoke # Quick smoke tests (~10 sec)\njust test-coverage # With coverage report\n```\n\n**Code quality:**\n```bash\njust lint # Check style\njust lint-fix # Auto-fix issues\njust format # Format code\njust typecheck # Type checking\njust check # All quality checks\n```\n\n**Before creating PR:**\n```bash\njust pre-merge # Run lint + test + coverage (required)\n```\n\n**Building & releasing:**\n```bash\njust build # Build distribution packages\njust prepare-release patch # Bump version, update CHANGELOG\njust publish-test # Publish to TestPyPI\njust publish-prod # Publish to PyPI\n```\n\n**Application:**\n```bash\njust run # Start the application\nmcp-orchestration # Or run directly\n```\n\n### Without `just` (Fallback)\n\nIf `just` installation fails, use commands directly:\n\n| Task | Command |\n|------|---------|\n| Run tests | `pytest` |\n| Build | `./scripts/build-dist.sh` |\n| Lint | `ruff check src/mcp_orchestration tests` |\n| Format | `black src/mcp_orchestration tests` |\n| Pre-merge | `./scripts/pre-merge.sh` |\n| Type check | `mypy src/mcp_orchestration` |\n\nSee [justfile](justfile) for complete command mappings.\n## Documentation\n\nThis project follows the [Di\u00e1taxis framework](https://diataxis.fr/) with three documentation directories:\n\n### For End Users (user-docs/)\nLearn how to **use** mcp-orchestration:\n- **[Getting Started Tutorial](user-docs/tutorials/01-getting-started.md)** - Learn the basics\n- **[How-To Guides](user-docs/how-to/)** - Solve specific problems\n- **[API Reference](user-docs/reference/)** - Look up specifications\n- **[Explanations](user-docs/explanation/)** - Understand concepts\n\n### For Project Planning (project-docs/)\nProject roadmap and architecture decisions:\n- **[ROADMAP.md](project-docs/ROADMAP.md)** - Long-term vision and milestones\n- **[Release Notes](project-docs/releases/)** - Version history and changes\n- **[Architecture Decisions](project-docs/decisions/)** - ADRs and design choices\n\n### For Contributors (dev-docs/)\nLearn how to **build** mcp-orchestration:\n- **[CONTRIBUTING.md](dev-docs/CONTRIBUTING.md)** - Contribution guidelines\n- **[DEVELOPMENT.md](dev-docs/DEVELOPMENT.md)** - Developer setup and architecture\n- **[TROUBLESHOOTING.md](dev-docs/TROUBLESHOOTING.md)** - Common development issues\n- **[Vision Documents](dev-docs/vision/)** - Strategic design guidance\n### For AI Coding Agents\n- **[AGENTS.md](AGENTS.md)** - Machine-readable instructions (OpenAI/Google standard)\n**Documentation Standard:**\n- **[DOCUMENTATION_STANDARD.md](DOCUMENTATION_STANDARD.md)** - Writing guidelines and templates\n\n## Project Principles\n\nThis project follows best practices for:\n\n- **Code Quality** - Linting (ruff), formatting (black), type checking (mypy)\n- **Testing** - Comprehensive test suite with 85%+ coverage\n- **Documentation** - Clear, up-to-date documentation following Di\u00e1taxis framework\n- **Agentic Coding** - Machine-readable instructions, stateful memory for AI agents\n## License\n\nMIT License - see [LICENSE](LICENSE)\n## Related Projects\n\n- [chora-base](https://github.com/liminalcommons/chora-base) - Python project template\n- [chora-composer](https://github.com/liminalcommons/chora-composer) - Configuration-driven artifact generation\n- [chora-platform](https://github.com/liminalcommons/chora-platform) - Shared platform tooling\n\n---\n\n\ud83e\udd16 Generated with [chora-base](https://github.com/liminalcommons/chora-base) template\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for centralized configuration management with cryptographic signatures and content-addressable storage",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/liminalcommons/mcp-orchestration#readme",
"Homepage": "https://github.com/liminalcommons/mcp-orchestration",
"Issues": "https://github.com/liminalcommons/mcp-orchestration/issues",
"Repository": "https://github.com/liminalcommons/mcp-orchestration"
},
"split_keywords": [
"configuration",
" cryptography",
" mcp",
" model-context-protocol",
" orchestration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ef7cf16f5170301922e78e5f95cfee1772c38cf2feae314b17a68614807d2ffc",
"md5": "565172acbaa387930bd1bfcca248d2d4",
"sha256": "93a82baadd476aee1d8895edc2aa05df578b070133645f617ae3b9f7e77d4480"
},
"downloads": -1,
"filename": "mcp_orchestration-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "565172acbaa387930bd1bfcca248d2d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 100341,
"upload_time": "2025-10-26T04:49:01",
"upload_time_iso_8601": "2025-10-26T04:49:01.856089Z",
"url": "https://files.pythonhosted.org/packages/ef/7c/f16f5170301922e78e5f95cfee1772c38cf2feae314b17a68614807d2ffc/mcp_orchestration-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "940f1fee9ccf9d5f040de27416c0a42e910fb71509a60b50643a10aafcf384fa",
"md5": "51f6844d160c621d66a33346e03662ca",
"sha256": "750b283a702f2a05baf4be4738cf5b86d022fd6a8b3f67c42627a3930b1e54c2"
},
"downloads": -1,
"filename": "mcp_orchestration-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "51f6844d160c621d66a33346e03662ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 561433,
"upload_time": "2025-10-26T04:49:03",
"upload_time_iso_8601": "2025-10-26T04:49:03.202813Z",
"url": "https://files.pythonhosted.org/packages/94/0f/1fee9ccf9d5f040de27416c0a42e910fb71509a60b50643a10aafcf384fa/mcp_orchestration-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 04:49:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "liminalcommons",
"github_project": "mcp-orchestration#readme",
"github_not_found": true,
"lcname": "mcp-orchestration"
}
JSON
