MCP Enterprise Server

Enterprise-grade Model Context Protocol (MCP) server with integrations to multiple free public APIs. Built with Python following best practices for production deployments, containerization, and CI/CD.

🌟 Features

Multiple API Integrations: Weather, News, Cryptocurrency, Country data, and more
Enterprise Architecture: Clean code with dependency injection, logging, caching, and error handling
Production Ready: Docker support, health checks, non-root user, multi-stage builds
Comprehensive Testing: Unit tests with pytest, coverage reporting, and HTTP mocking
CI/CD Pipeline: GitHub Actions for testing, linting, security scanning, and deployment
Configuration Management: Environment-based config with validation using Pydantic
Structured Logging: JSON logging with structlog for production observability
HTTP Client: Retry logic, timeout handling, and proper error management
Caching: Built-in cache with TTL support for API responses
Type Safety: Full type hints and mypy checking

🚀 Quick Start

Prerequisites

Python 3.10 or higher
Docker and Docker Compose (optional)
API keys for some services (see Configuration)

Local Development

Clone the repository

   git clone https://github.com/yourusername/mcp-enterprise-server.git
   cd mcp-enterprise-server

Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies

   pip install -e ".[dev]"

Configure environment

   cp .env.example .env
   # Edit .env with your API keys

Run the server

   python -m mcp_server.main

📖 Usage

Connecting to the MCP Server

The MCP server uses the Model Context Protocol (MCP) over stdio transport. It's designed to be used with MCP clients like Claude Desktop, IDEs, or custom applications.

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-enterprise": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "env": {
        "OPENWEATHER_API_KEY": "your_openweather_key",
        "NEWSAPI_KEY": "your_news_api_key",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Or if using Docker:

{
  "mcpServers": {
    "mcp-enterprise": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENWEATHER_API_KEY=your_key",
        "-e",
        "NEWSAPI_KEY=your_key",
        "mcp-enterprise-server:latest"
      ]
    }
  }
}

Using with Custom MCP Client

Here's a Python example using the MCP SDK:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "mcp_server.main"],
        env={
            "OPENWEATHER_API_KEY": "your_key",
            "NEWSAPI_KEY": "your_key"
        }
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in tools.tools]}")

            # Call a tool
            result = await session.call_tool("get_weather", arguments={"city": "London"})
            print(f"Weather result: {result.content}")

asyncio.run(main())

Available Tools and Examples

1. Weather Tools

get_weather - Get current weather for a city

# Arguments
{
  "city": "London",
  "country_code": "UK"  # Optional
}

# Response
{
  "city": "London",
  "country": "GB",
  "temperature": 15.5,
  "feels_like": 14.2,
  "humidity": 72,
  "description": "partly cloudy",
  "wind_speed": 5.5
}

get_forecast - Get 5-day weather forecast

# Arguments
{
  "city": "Paris",
  "country_code": "FR"  # Optional
}

# Response
{
  "city": "Paris",
  "country": "FR",
  "forecasts": [
    {
      "date": "2025-11-18",
      "temperature": 12.5,
      "description": "light rain",
      "humidity": 80,
      "wind_speed": 4.2
    }
    // ... more forecast entries
  ]
}

2. News Tools

get_news_headlines - Get top headlines

# Arguments
{
  "country": "us",        # Optional: us, gb, fr, de, etc.
  "category": "technology" # Optional: business, technology, sports, etc.
}

# Response
{
  "total_results": 20,
  "articles": [
    {
      "title": "Breaking Tech News",
      "description": "Latest developments in AI...",
      "url": "https://example.com/article",
      "source": "TechCrunch",
      "published_at": "2025-11-18T10:30:00Z",
      "author": "John Doe"
    }
    // ... more articles
  ]
}

search_news - Search news by keyword

# Arguments
{
  "query": "artificial intelligence",
  "language": "en",  # Optional
  "sort_by": "publishedAt"  # Optional: relevancy, popularity, publishedAt
}

# Response
{
  "total_results": 150,
  "articles": [
    // ... article objects
  ]
}

3. Cryptocurrency Tools

get_crypto_price - Get cryptocurrency prices

# Arguments
{
  "coin_ids": "bitcoin,ethereum,cardano",
  "vs_currencies": "usd,eur"  # Optional, default: usd
}

# Response
{
  "bitcoin": {
    "usd": 45000.50,
    "eur": 42000.30
  },
  "ethereum": {
    "usd": 3200.75,
    "eur": 2980.40
  }
}

get_trending_crypto - Get trending cryptocurrencies

# Arguments
{}  # No arguments required

# Response
{
  "coins": [
    {
      "id": "bitcoin",
      "name": "Bitcoin",
      "symbol": "BTC",
      "market_cap_rank": 1,
      "price_btc": 1.0
    }
    // ... more trending coins
  ]
}

4. Country Information Tools

get_country_info - Get detailed country information

# Arguments
{
  "country": "france"  # Name, code, or capital
}

# Response
{
  "name": "France",
  "official_name": "French Republic",
  "capital": "Paris",
  "region": "Europe",
  "subregion": "Western Europe",
  "population": 67391582,
  "area": 551695,
  "languages": ["French"],
  "currencies": ["EUR"],
  "timezones": ["UTC+01:00"],
  "flag": "🇫🇷"
}

get_all_countries - Get all countries data

# Arguments
{
  "region": "europe"  # Optional: africa, americas, asia, europe, oceania
}

# Response
{
  "total": 44,
  "countries": [
    {
      "name": "France",
      "capital": "Paris",
      "population": 67391582,
      // ... more fields
    }
    // ... more countries
  ]
}

5. Demo/Testing Tools

get_sample_posts - Get sample blog posts

# Arguments
{
  "limit": 5  # Optional, default: 10
}

# Response
{
  "posts": [
    {
      "id": 1,
      "title": "Sample Post",
      "body": "Post content...",
      "userId": 1
    }
    // ... more posts
  ]
}

get_sample_users - Get sample users data

# Arguments
{
  "limit": 3  # Optional, default: 10
}

# Response
{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "username": "johndoe",
      "phone": "123-456-7890",
      "website": "example.com"
    }
    // ... more users
  ]
}

Error Handling

All tools return errors in a consistent format:

# Error Response
{
  "error": "API request failed",
  "details": "Invalid API key",
  "tool": "get_weather",
  "status_code": 401  # If applicable
}

Common error scenarios:

Invalid API Key: Check your .env configuration
Rate Limit Exceeded: Wait before making more requests
Invalid Arguments: Verify argument types and required fields
Network Errors: Check internet connection and API availability

Testing Tools

You can test individual tools using the Python client or by checking logs:

# Watch logs in development
tail -f logs/mcp_server.log

# Or with Docker
docker-compose logs -f

Docker Deployment

Build and run with Docker Compose

   docker-compose up -d

View logs

   docker-compose logs -f

Stop the server

   docker-compose down

📋 Available Tools

Weather Tools

get_weather - Get current weather for a city (OpenWeatherMap)
get_forecast - Get 5-day weather forecast

News Tools

get_news_headlines - Get top headlines by country/category (NewsAPI)
search_news - Search news articles by keyword

Cryptocurrency Tools

get_crypto_price - Get cryptocurrency prices (CoinGecko)
get_trending_crypto - Get trending cryptocurrencies

Country Tools

get_country_info - Get detailed country information (REST Countries)
get_all_countries - Get all countries data

Demo Tools

get_sample_posts - Get sample blog posts (JSONPlaceholder)
get_sample_users - Get sample users data

⚙️ Configuration

Configuration is managed through environment variables. Copy .env.example to .env and configure:

# Environment
ENVIRONMENT=development  # development, staging, production

# Logging
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=json  # json, console

# API Keys (Optional - some work without keys)
OPENWEATHER_API_KEY=your_key_here  # Get from https://openweathermap.org/api
NEWSAPI_KEY=your_key_here  # Get from https://newsapi.org/

# HTTP Settings
HTTP_TIMEOUT=30
HTTP_MAX_RETRIES=3

# Cache Settings
CACHE_ENABLED=true
CACHE_TTL=300

Free API Keys

OpenWeatherMap (Free tier: 1000 calls/day)

- Sign up: https://openweathermap.org/api

NewsAPI (Free tier: 100 requests/day)

- Sign up: https://newsapi.org/

CoinGecko - No API key needed for basic usage

REST Countries - No API key needed

JSONPlaceholder - No API key needed

🏗️ Architecture

src/mcp_server/
├── __init__.py          # Package initialization
├── main.py              # MCP server implementation
├── config.py            # Configuration management (Pydantic)
├── logger.py            # Structured logging setup
├── http_client.py       # HTTP client with retry logic
├── cache.py             # In-memory cache with TTL
└── tools.py             # API integrations (Weather, News, Crypto, etc.)

tests/
├── __init__.py
├── conftest.py          # Pytest configuration and fixtures
├── test_config.py       # Configuration tests
├── test_cache.py        # Cache tests
├── test_http_client.py  # HTTP client tests
└── test_tools.py        # API tools tests

Design Patterns

Dependency Injection: Services are injected rather than instantiated
Factory Pattern: Singleton factories for HTTP client and cache
Repository Pattern: API tools encapsulate external API access
Configuration Pattern: Centralized config with Pydantic validation
Cache-Aside: Caching layer for API responses

🧪 Testing

Run the complete test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=src/mcp_server --cov-report=html

# Run specific test file
pytest tests/test_config.py

# Run with verbose output
pytest -v

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/ --ignore-missing-imports

# Run all quality checks
pre-commit run --all-files

🐳 Docker

Build Docker Image

docker build -t mcp-enterprise-server:latest .

Run Docker Container

docker run -d \
  --name mcp-server \
  -e OPENWEATHER_API_KEY=your_key \
  -e NEWSAPI_KEY=your_key \
  -v $(pwd)/logs:/app/logs \
  mcp-enterprise-server:latest

Multi-stage Build Benefits

Ultra-fast builds: Uses uv - up to 10-100x faster than pip
Smaller production image: ~240MB optimized size
Separate build and runtime dependencies: Clean separation of concerns
Security: Runs as non-root user (mcpuser)
Optimized layer caching: Better Docker layer utilization
Bytecode compilation: Pre-compiled Python bytecode for faster startup

Note: The Dockerfile uses uv, an extremely fast Python package installer and resolver written in Rust. This significantly reduces Docker build times compared to traditional pip-based builds.

🚀 Deployment

Kubernetes

Example deployment configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
        - name: mcp-server
          image: ghcr.io/yourusername/mcp-enterprise-server:latest
          envFrom:
            - secretRef:
                name: mcp-server-secrets
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "200m"
          livenessProbe:
            exec:
              command:
                - python
                - -c
                - "import sys; sys.exit(0)"
            initialDelaySeconds: 10
            periodSeconds: 30

Cloud Platforms

AWS ECS/Fargate: See detailed AWS Deployment Guide
Google Cloud Run: Deploy directly from container registry
Azure Container Instances: One-command deployment
Heroku: Use the Dockerfile for deployment
Kubernetes: See k8s/deployment.yaml for configuration

For comprehensive AWS deployment instructions including ECS, Fargate, Lambda, EC2, and App Runner, see the AWS Deployment Guide.

📊 Monitoring and Observability

Structured Logging

All logs are structured JSON (in production) for easy parsing:

{
  "event": "Tool called",
  "tool": "get_weather",
  "arguments": { "city": "London" },
  "level": "info",
  "timestamp": "2025-11-18T10:30:45.123456Z"
}

Metrics

Integrate with monitoring tools:

Prometheus for metrics collection
Grafana for visualization
ELK Stack for log aggregation
Sentry for error tracking

🔒 Security

Non-root user: Container runs as unprivileged user
Dependency scanning: Automated with GitHub Actions
Secret management: Environment variables, never hardcoded
Input validation: Pydantic models validate all inputs
HTTPS only: All API calls use secure connections
Rate limiting: Built-in support (configurable)

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow PEP 8 style guide
Add tests for new features
Update documentation
Use type hints
Run pre-commit hooks

📝 License

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

🙏 Acknowledgments

📞 Support

For issues and questions:

Open an issue on GitHub
Check existing documentation
Review API provider documentation

� Documentation

API Documentation - Detailed API specifications
AWS Deployment Guide - Complete AWS deployment instructions
General Deployment Guide - Docker, Kubernetes, and cloud platforms
Contributing Guidelines - How to contribute to the project

�🗺️ Roadmap

[ ] Add more API integrations (GitHub, OpenAI, etc.)
[ ] Implement rate limiting per tool
[ ] Add Redis cache backend option
[ ] GraphQL support
[ ] WebSocket support for real-time updates
[ ] Admin dashboard
[ ] Prometheus metrics endpoint
[ ] OpenAPI/Swagger documentation

trial MCP

快速接入

详细介绍