<div align="center">
# 🏥 Genesis MCP Core SDK
**The foundational SDK for building Model Context Protocol (MCP) 2025-06-18 compliant servers**
[](https://modelcontextprotocol.io)
[](https://python.org)
[](https://python-poetry.org)
[](LICENSE)
**🚀 Production-Ready • 🔄 Backward Compatible • 🏥 Healthcare Optimized • 🛠️ Developer Friendly**
---
</div>
## 📋 **Table of Contents**
- [🎯 Overview](#-overview)
- [✨ Features](#-features)
- [🚀 Quick Start](#-quick-start)
- [🏗️ Architecture](#%EF%B8%8F-architecture)
- [📚 API Reference](#-api-reference)
- [🛠️ Development](#%EF%B8%8F-development)
- [🤝 Contributing](#-contributing)
## 🎯 **Overview**
Genesis MCP Core SDK is a comprehensive, production-ready foundation for building Model Context Protocol servers. It provides everything you need to create robust, scalable, and compliant MCP servers with minimal boilerplate code.
**Perfect for:**
- 🏥 Healthcare AI applications requiring API integration
- 🔧 Enterprise tools needing structured AI workflows
- 🚀 Rapid prototyping of MCP-enabled services
- 📦 Building reusable connector libraries
## ✨ **Features**
### **🌐 Full MCP 2025-06-18 Compliance**
- **Modern Protocol**: Single `/mcp` endpoint with JSON-RPC 2.0
- **Backward Compatible**: Legacy `/sse` + `/messages` endpoints
- **Discovery APIs**: REST endpoints for tools and health monitoring
- **Streaming Support**: Real-time responses with Server-Sent Events
### **🔧 Advanced Capabilities**
- **Elicitation Support**: Human-in-the-loop parameter collection
- **Structured Output**: JSON Schema validation for consistent responses
- **Security Hardening**: Anti-tool-poisoning, input sanitization
- **Error Handling**: Comprehensive error codes and graceful degradation
### **🏥 Healthcare Integration**
- **Autonomize Connector SDK**: Seamless integration with healthcare APIs
- **Dynamic Discovery**: JSON-based connector registration
- **Medical Standards**: Built-in support for medical coding systems
- **HIPAA Considerations**: Security-first architecture
### **🛠️ Developer Experience**
- **Built-in Templates**: CLI tool for generating client-specific servers
- **Hot Reloading**: Dynamic connector discovery and registration
- **Comprehensive Logging**: Structured logging with contextual information
- **Type Safety**: Full TypeScript-style type hints with Pydantic
## 🚀 **Quick Start**
### **1. Installation**
```bash
# Install the SDK
pip install genesis-mcp-core
# Or with Poetry (recommended)
poetry add genesis-mcp-core
```
### **2. Create Your First Server**
```bash
# Generate a new MCP server project
genesis-mcp create my-mcp-server --template=basic
# Navigate to your project
cd my-mcp-server
# Configure environment
cp env.example .env
# Edit .env with your API credentials
# Install dependencies and run
poetry install
poetry run python main.py
```
### **3. Add Your Connectors**
Place your connector JSON files in the `connectors/` directory:
```json
{
"name": "my_api",
"base_url": "https://api.example.com",
"auth": {
"type": "oauth2",
"client_id_env": "MY_API_CLIENT_ID",
"client_secret_env": "MY_API_CLIENT_SECRET"
},
"endpoints": {
"get_data": {
"path": "/data/{id}",
"method": "GET"
}
}
}
```
### **4. Test Your Server**
```bash
# Check health
curl http://localhost:8002/health
# List available tools
curl http://localhost:8002/tools
# Modern MCP endpoint
curl -X POST http://localhost:8002/mcp \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2025-06-18" \
-d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1, "params": {}}'
```
## 🏗️ **Architecture**
### **Core Components**
```mermaid
graph TD
A[MCP Client] --> B[Genesis MCP Core Server]
B --> C[Connector Registry]
C --> D[Autonomize Bridge]
D --> E[Healthcare APIs]
B --> F[Modern /mcp Endpoint]
B --> G[Legacy /sse + /messages]
B --> H[REST /tools + /health]
C --> I[JSON Connector Configs]
C --> J[Dynamic Tool Generation]
style B fill:#e1f5fe,stroke:#01579b,stroke-width:2px
style C fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style D fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
```
### **Request Flow**
1. **Client Connection**: MCP client connects via modern or legacy endpoints
2. **Tool Discovery**: Server exposes dynamically generated tools from connectors
3. **Tool Execution**: Client calls tools, server routes to appropriate connector
4. **Response Handling**: Structured responses with error handling and validation
### **Connector System**
- **JSON-Based**: Define APIs using simple JSON configurations
- **Dynamic Loading**: Connectors discovered automatically from config directory
- **Type Safety**: Automatic schema generation and validation
- **Extensible**: Easy to add new connector types and authentication methods
## 📚 **API Reference**
### **GenesisMCPServer**
The main server class providing full MCP functionality:
```python
from genesis_mcp_core import GenesisMCPServer
from pathlib import Path
# Basic usage
server = GenesisMCPServer(
connector_config_dir=Path("./connectors"),
host="0.0.0.0",
port=8002,
debug=False
)
# Run the server
await server.run()
```
### **Built-in CLI**
Generate new projects from templates:
```bash
# Available templates
genesis-mcp create --help
# Basic server (currently available)
genesis-mcp create my-server --template=basic
```
### **Environment Configuration**
```bash
# Server settings
SERVER_HOST=0.0.0.0
SERVER_PORT=8002
SERVER_DEBUG=false
# Logging
LOGGING_LEVEL=INFO
LOGGING_FORMAT=structured
# Connector enablement (auto-discovered from JSON files)
ENABLE_MY_CONNECTOR=true
ENABLE_HEALTHCARE_API=true
# API credentials
MY_API_CLIENT_ID=your_client_id
MY_API_CLIENT_SECRET=your_secret
```
### **Supported Endpoints**
| Endpoint | Method | Description | Compatibility |
|----------|--------|-------------|---------------|
| `/mcp` | POST | Modern MCP 2025-06-18 endpoint | ✅ Latest |
| `/sse` | GET | Server-Sent Events stream | 🔄 Legacy |
| `/messages` | POST | Classic message handling | 🔄 Legacy |
| `/tools` | GET | REST API tool discovery | 📊 Discovery |
| `/health` | GET | Health check and capabilities | 📊 Monitoring |
## 🛠️ **Development**
### **Local Development**
```bash
# Clone the repository
git clone <repository-url>
cd genesis-mcp-core
# Install dependencies
poetry install
# Run tests
poetry run pytest
# Run example server
poetry run python test_server.py
```
### **Testing**
```bash
# Run all tests
poetry run pytest
# Test with coverage
poetry run pytest --cov=genesis_mcp_core
# Test backward compatibility
poetry run python test_backward_compatibility.py
# Integration tests
poetry run pytest tests/integration/
```
### **Building and Publishing**
```bash
# Build the package
poetry build
# Publish to PyPI
poetry publish
# Install locally for testing
pip install dist/genesis_mcp_core-*.whl
```
## 🤝 **Contributing**
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### **Development Setup**
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
### **Code Standards**
- Python 3.12+
- Type hints required
- 90%+ test coverage
- Black code formatting
- Comprehensive documentation
## 📄 **License**
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 **Acknowledgments**
- [Model Context Protocol](https://modelcontextprotocol.io) specification
- [Autonomize AI](https://autonomize.ai) for healthcare API integration
- [FastAPI](https://fastapi.tiangolo.com) for the web framework
- [Pydantic](https://pydantic.dev) for data validation
---
<div align="center">
**Built with ❤️ for the MCP community**
[Documentation](https://docs.genesis-mcp.io) • [Examples](./examples/) • [Community](https://discord.gg/genesis-mcp)
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/your-org/genesis-mcp-core",
"name": "genesis-mcp-core",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.12",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, ai, llm, connector, sdk",
"author": "Your Name",
"author_email": "your.email@example.com",
"download_url": "https://files.pythonhosted.org/packages/2b/cc/9063996f98bdfd35d707035007f0a860c4a15aae1f1f11765acc199e1902/genesis_mcp_core-0.0.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# \ud83c\udfe5 Genesis MCP Core SDK\n\n**The foundational SDK for building Model Context Protocol (MCP) 2025-06-18 compliant servers**\n\n[](https://modelcontextprotocol.io)\n[](https://python.org)\n[](https://python-poetry.org)\n[](LICENSE)\n\n**\ud83d\ude80 Production-Ready \u2022 \ud83d\udd04 Backward Compatible \u2022 \ud83c\udfe5 Healthcare Optimized \u2022 \ud83d\udee0\ufe0f Developer Friendly**\n\n---\n\n</div>\n\n## \ud83d\udccb **Table of Contents**\n\n- [\ud83c\udfaf Overview](#-overview)\n- [\u2728 Features](#-features)\n- [\ud83d\ude80 Quick Start](#-quick-start)\n- [\ud83c\udfd7\ufe0f Architecture](#%EF%B8%8F-architecture)\n- [\ud83d\udcda API Reference](#-api-reference)\n- [\ud83d\udee0\ufe0f Development](#%EF%B8%8F-development)\n- [\ud83e\udd1d Contributing](#-contributing)\n\n## \ud83c\udfaf **Overview**\n\nGenesis MCP Core SDK is a comprehensive, production-ready foundation for building Model Context Protocol servers. It provides everything you need to create robust, scalable, and compliant MCP servers with minimal boilerplate code.\n\n**Perfect for:**\n- \ud83c\udfe5 Healthcare AI applications requiring API integration\n- \ud83d\udd27 Enterprise tools needing structured AI workflows\n- \ud83d\ude80 Rapid prototyping of MCP-enabled services\n- \ud83d\udce6 Building reusable connector libraries\n\n## \u2728 **Features**\n\n### **\ud83c\udf10 Full MCP 2025-06-18 Compliance**\n- **Modern Protocol**: Single `/mcp` endpoint with JSON-RPC 2.0\n- **Backward Compatible**: Legacy `/sse` + `/messages` endpoints\n- **Discovery APIs**: REST endpoints for tools and health monitoring\n- **Streaming Support**: Real-time responses with Server-Sent Events\n\n### **\ud83d\udd27 Advanced Capabilities**\n- **Elicitation Support**: Human-in-the-loop parameter collection\n- **Structured Output**: JSON Schema validation for consistent responses\n- **Security Hardening**: Anti-tool-poisoning, input sanitization\n- **Error Handling**: Comprehensive error codes and graceful degradation\n\n### **\ud83c\udfe5 Healthcare Integration**\n- **Autonomize Connector SDK**: Seamless integration with healthcare APIs\n- **Dynamic Discovery**: JSON-based connector registration\n- **Medical Standards**: Built-in support for medical coding systems\n- **HIPAA Considerations**: Security-first architecture\n\n### **\ud83d\udee0\ufe0f Developer Experience**\n- **Built-in Templates**: CLI tool for generating client-specific servers\n- **Hot Reloading**: Dynamic connector discovery and registration\n- **Comprehensive Logging**: Structured logging with contextual information\n- **Type Safety**: Full TypeScript-style type hints with Pydantic\n\n## \ud83d\ude80 **Quick Start**\n\n### **1. Installation**\n\n```bash\n# Install the SDK\npip install genesis-mcp-core\n\n# Or with Poetry (recommended)\npoetry add genesis-mcp-core\n```\n\n### **2. Create Your First Server**\n\n```bash\n# Generate a new MCP server project\ngenesis-mcp create my-mcp-server --template=basic\n\n# Navigate to your project\ncd my-mcp-server\n\n# Configure environment\ncp env.example .env\n# Edit .env with your API credentials\n\n# Install dependencies and run\npoetry install\npoetry run python main.py\n```\n\n### **3. Add Your Connectors**\n\nPlace your connector JSON files in the `connectors/` directory:\n\n```json\n{\n \"name\": \"my_api\",\n \"base_url\": \"https://api.example.com\",\n \"auth\": {\n \"type\": \"oauth2\",\n \"client_id_env\": \"MY_API_CLIENT_ID\",\n \"client_secret_env\": \"MY_API_CLIENT_SECRET\"\n },\n \"endpoints\": {\n \"get_data\": {\n \"path\": \"/data/{id}\",\n \"method\": \"GET\"\n }\n }\n}\n```\n\n### **4. Test Your Server**\n\n```bash\n# Check health\ncurl http://localhost:8002/health\n\n# List available tools\ncurl http://localhost:8002/tools\n\n# Modern MCP endpoint\ncurl -X POST http://localhost:8002/mcp \\\n -H \"Content-Type: application/json\" \\\n -H \"MCP-Protocol-Version: 2025-06-18\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1, \"params\": {}}'\n```\n\n## \ud83c\udfd7\ufe0f **Architecture**\n\n### **Core Components**\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Genesis MCP Core Server]\n B --> C[Connector Registry]\n C --> D[Autonomize Bridge]\n D --> E[Healthcare APIs]\n \n B --> F[Modern /mcp Endpoint]\n B --> G[Legacy /sse + /messages]\n B --> H[REST /tools + /health]\n \n C --> I[JSON Connector Configs]\n C --> J[Dynamic Tool Generation]\n \n style B fill:#e1f5fe,stroke:#01579b,stroke-width:2px\n style C fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px\n style D fill:#fff3e0,stroke:#ef6c00,stroke-width:2px\n```\n\n### **Request Flow**\n\n1. **Client Connection**: MCP client connects via modern or legacy endpoints\n2. **Tool Discovery**: Server exposes dynamically generated tools from connectors\n3. **Tool Execution**: Client calls tools, server routes to appropriate connector\n4. **Response Handling**: Structured responses with error handling and validation\n\n### **Connector System**\n\n- **JSON-Based**: Define APIs using simple JSON configurations\n- **Dynamic Loading**: Connectors discovered automatically from config directory\n- **Type Safety**: Automatic schema generation and validation\n- **Extensible**: Easy to add new connector types and authentication methods\n\n## \ud83d\udcda **API Reference**\n\n### **GenesisMCPServer**\n\nThe main server class providing full MCP functionality:\n\n```python\nfrom genesis_mcp_core import GenesisMCPServer\nfrom pathlib import Path\n\n# Basic usage\nserver = GenesisMCPServer(\n connector_config_dir=Path(\"./connectors\"),\n host=\"0.0.0.0\",\n port=8002,\n debug=False\n)\n\n# Run the server\nawait server.run()\n```\n\n### **Built-in CLI**\n\nGenerate new projects from templates:\n\n```bash\n# Available templates\ngenesis-mcp create --help\n\n# Basic server (currently available)\ngenesis-mcp create my-server --template=basic\n```\n\n### **Environment Configuration**\n\n```bash\n# Server settings\nSERVER_HOST=0.0.0.0\nSERVER_PORT=8002\nSERVER_DEBUG=false\n\n# Logging\nLOGGING_LEVEL=INFO\nLOGGING_FORMAT=structured\n\n# Connector enablement (auto-discovered from JSON files)\nENABLE_MY_CONNECTOR=true\nENABLE_HEALTHCARE_API=true\n\n# API credentials\nMY_API_CLIENT_ID=your_client_id\nMY_API_CLIENT_SECRET=your_secret\n```\n\n### **Supported Endpoints**\n\n| Endpoint | Method | Description | Compatibility |\n|----------|--------|-------------|---------------|\n| `/mcp` | POST | Modern MCP 2025-06-18 endpoint | \u2705 Latest |\n| `/sse` | GET | Server-Sent Events stream | \ud83d\udd04 Legacy |\n| `/messages` | POST | Classic message handling | \ud83d\udd04 Legacy |\n| `/tools` | GET | REST API tool discovery | \ud83d\udcca Discovery |\n| `/health` | GET | Health check and capabilities | \ud83d\udcca Monitoring |\n\n## \ud83d\udee0\ufe0f **Development**\n\n### **Local Development**\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd genesis-mcp-core\n\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Run example server\npoetry run python test_server.py\n```\n\n### **Testing**\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Test with coverage\npoetry run pytest --cov=genesis_mcp_core\n\n# Test backward compatibility\npoetry run python test_backward_compatibility.py\n\n# Integration tests\npoetry run pytest tests/integration/\n```\n\n### **Building and Publishing**\n\n```bash\n# Build the package\npoetry build\n\n# Publish to PyPI\npoetry publish\n\n# Install locally for testing\npip install dist/genesis_mcp_core-*.whl\n```\n\n## \ud83e\udd1d **Contributing**\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### **Development Setup**\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n### **Code Standards**\n\n- Python 3.12+\n- Type hints required\n- 90%+ test coverage\n- Black code formatting\n- Comprehensive documentation\n\n## \ud83d\udcc4 **License**\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f **Acknowledgments**\n\n- [Model Context Protocol](https://modelcontextprotocol.io) specification\n- [Autonomize AI](https://autonomize.ai) for healthcare API integration\n- [FastAPI](https://fastapi.tiangolo.com) for the web framework\n- [Pydantic](https://pydantic.dev) for data validation\n\n---\n\n<div align=\"center\">\n\n**Built with \u2764\ufe0f for the MCP community**\n\n[Documentation](https://docs.genesis-mcp.io) \u2022 [Examples](./examples/) \u2022 [Community](https://discord.gg/genesis-mcp)\n\n</div>",
"bugtrack_url": null,
"license": "MIT",
"summary": "Genesis MCP Core - A powerful Model Context Protocol server SDK with built-in connector support",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/your-org/genesis-mcp-core",
"Repository": "https://github.com/your-org/genesis-mcp-core"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" ai",
" llm",
" connector",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db201a3a8867508f4f1482e75333ceedf29930590712c22295f090a3d82f2d56",
"md5": "9ee9626c9a09ccac91f18417511e66a1",
"sha256": "3007de9e9f417538d5a6deb944273131546156d22acc62339d12f503ce014c7c"
},
"downloads": -1,
"filename": "genesis_mcp_core-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ee9626c9a09ccac91f18417511e66a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.12",
"size": 51023,
"upload_time": "2025-08-12T23:12:38",
"upload_time_iso_8601": "2025-08-12T23:12:38.836074Z",
"url": "https://files.pythonhosted.org/packages/db/20/1a3a8867508f4f1482e75333ceedf29930590712c22295f090a3d82f2d56/genesis_mcp_core-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2bcc9063996f98bdfd35d707035007f0a860c4a15aae1f1f11765acc199e1902",
"md5": "dd22eebbc35594ad666adb08af6f1337",
"sha256": "f7d2f998f11c62b73b5de9dcb5f3e4c1f08d2ffcc0f15098ede414982e17e695"
},
"downloads": -1,
"filename": "genesis_mcp_core-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "dd22eebbc35594ad666adb08af6f1337",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.12",
"size": 38808,
"upload_time": "2025-08-12T23:12:40",
"upload_time_iso_8601": "2025-08-12T23:12:40.369311Z",
"url": "https://files.pythonhosted.org/packages/2b/cc/9063996f98bdfd35d707035007f0a860c4a15aae1f1f11765acc199e1902/genesis_mcp_core-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 23:12:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-org",
"github_project": "genesis-mcp-core",
"github_not_found": true,
"lcname": "genesis-mcp-core"
}
JSON
