MCP Gateway and Inspector

A modular Microservice Communication Protocol (MCP) Gateway package for wrapping GraphQL APIs with standardized tracing, authentication, and error handling. Includes a full-featured web inspector for testing and monitoring.

Features

MCP Gateway Package

• Modular Design: Reusable Python package that can be installed via pip or used standalone
• Tracing: Automatic correlation ID generation and propagation
• Authentication: Bearer token validation middleware
• Error Handling: Standardized MCP error codes and responses
• GraphQL Proxy: Seamless proxying to backend GraphQL services

MCP Inspector Web App

• Request Builder: Visual GraphQL query editor
• Response Viewer: Formatted JSON response display with error highlighting
• Request History: Track and replay previous requests
• Environment Management: Switch between dev/staging/prod environments
• Request Templates: Save and reuse common queries
• Export/Import: Share requests as JSON files
• Correlation ID Tracking: View and copy correlation IDs for debugging

Installation

Python Package

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .

Inspector Web App

cd inspector
npm install

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Key configuration options:

• TARGET_GRAPHQL_URL: Backend GraphQL API endpoint
• PORT: Gateway server port (default: 8080)
• ENABLE_AUTH: Enable/disable authentication (default: true)
• LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)

Usage

Running the Gateway

# Using uvicorn directly
uvicorn gateway.main:app --reload --host 0.0.0.0 --port 8080

# Or using Python
python -m gateway.main

The gateway will be available at http://localhost:8080

Running Mock Backend (for Testing)

If you don't have a real GraphQL backend, you can use the included mock backend for testing:

# Easy way: Use the startup script
./start_mock_backend.sh

# Or manually:
python3 mock_backend.py
# or
uvicorn mock_backend:app --reload --port 8081

The mock backend will be available at http://localhost:8081 and supports common GraphQL queries like:

• query { hello }
• query { user(id: "1") { id name email } }
• query { users { id name email } }
• mutation { createUser(input: {name: "John", email: "john@example.com"}) { id } }

Important:

• Make sure the mock backend is running before starting the gateway
• Test the backend: curl http://localhost:8081/health
• If you get "Connection refused", the mock backend is not running
• See QUICKSTART.md for detailed troubleshooting

Running MCP Server for LLM Integration

The CRM Employee Management MCP Server (Model Context Protocol) exposes CRM functions as tools that LLMs can use:

# Install MCP SDK first
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

# Start the MCP server
./start_crm_mcp_mcp.sh
# or
python3 crm_mcp_server_mcp.py

MCP Server Tools:

• list_employees - List/search employees with filters
• get_employee - Get employee details by ID
• create_employee - Create new employee
• update_employee - Update employee information
• delete_employee - Delete employee (soft delete)
• search_employees - Search employees by name, email, etc.
• get_employee_stats - Get employee statistics
• get_departments - List all departments

Configuration: See MCP_SETUP.md for detailed setup instructions for Claude Desktop, Cursor, and other MCP-compatible clients.

Example Usage with LLM: Once connected to Claude Desktop or Cursor, you can use natural language:

• "List all employees in the Engineering department"
• "Show me employee statistics"
• "Create a new employee named John Doe in Sales"
• "Search for employees with 'engineer' in their position"

Running CRM REST API Server

The CRM Employee Management REST API Server is a comprehensive REST API server for managing employee data:

# Easy way: Use the startup script
./start_crm_mcp.sh

# Or manually:
python3 crm_mcp_server.py
# or
uvicorn crm_mcp_server:app --reload --port 8083

The CRM server will be available at http://localhost:8083 and provides:

Employee Management Endpoints:

• GET /api/employees - List all employees (with filtering, pagination, sorting)
• GET /api/employees/{id} - Get employee details
• POST /api/employees - Create new employee
• PUT /api/employees/{id} - Update employee
• DELETE /api/employees/{id} - Delete employee (soft delete)
• GET /api/employees/search?q={query} - Search employees
• GET /api/employees/department/{dept} - Get employees by department
• GET /api/employees/stats - Get employee statistics
• GET /api/departments - List all departments

Example Employee Data Model:

{
  "id": "emp-001",
  "firstName": "Ahmet",
  "lastName": "Yılmaz",
  "email": "ahmet.yilmaz@company.com",
  "phone": "+90 555 123 4567",
  "department": "Engineering",
  "position": "Senior Software Engineer",
  "salary": 85000.0,
  "hireDate": "2020-03-15",
  "status": "active",
  "address": "Atatürk Cad. No:123",
  "city": "Istanbul",
  "country": "Turkey",
  "managerId": null,
  "skills": ["Python", "JavaScript", "React", "Node.js"],
  "notes": "Team lead candidate"
}

Running the Inspector

cd inspector
npm run dev

The inspector will be available at http://localhost:3000 and includes:

• GraphQL Inspector: Test GraphQL queries and mutations
• CRM Manager: Full-featured employee management interface with:
  • Employee list with search and filtering
  • Add/Edit/Delete employees
  • Department-based filtering
  • Employee statistics dashboard

Quick Start - All Services at Once

To start all four services (Mock Backend, Gateway, CRM MCP Server, and Inspector) with a single command:

./dev-live.sh

This script will:

• Check dependencies and port availability
• Start all services in separate terminal windows
• Display service URLs and useful endpoints
• Show informative status messages

Note: On macOS, the script opens new Terminal windows. On Linux, it uses gnome-terminal.

Services Started:

1. Mock Backend (port 8081) - GraphQL test backend
2. Gateway (port 8080) - MCP Gateway with REST and GraphQL proxy
3. CRM MCP Server (port 8083) - Employee management REST API
4. Inspector (port 3000) - Web UI for testing and management

Stopping All Services

To stop all services and free up ports:

./dev-live-shutdown.sh

This script will stop all running services (Mock Backend, Gateway, CRM MCP Server, Inspector) and verify that ports 8081, 8080, 8083, and 3000 are free.

Using the MCP Package in Your Project

As a Package

from mcp import MCPGateway, TracingMiddleware, AuthMiddleware
from fastapi import FastAPI

app = FastAPI()
app.add_middleware(TracingMiddleware)

gateway = MCPGateway(target_url="http://backend:8081/graphql")
auth = AuthMiddleware()

@app.post("/graphql")
async def graphql_proxy(request: Request, graphql_request: MCPRequest):
    auth.validate_request(request)
    return await gateway.proxy_graphql_request(request, graphql_request)

Standalone Module

Copy the mcp/ directory to your project and import as needed.

API Endpoints

Gateway Endpoints

• POST /graphql - Proxy GraphQL requests
• POST /mcp/proxy - Dynamic GraphQL proxy (for Inspector)
• POST /mcp/rest-proxy - REST API proxy (supports GET, POST, PUT, DELETE, PATCH)
• GET /health - Health check endpoint

Request Format

{
  "query": "query { hello }",
  "operationName": "MyQuery",
  "variables": { "key": "value" }
}

Authentication

Include Bearer token in Authorization header:

Authorization: Bearer your-token-here

Error Codes

• MCP-401: Authentication failed
• MCP-503: Backend service unavailable
• BACKEND-ERROR: Backend service error
• MCP-500: Internal server error

Project Structure

mcp/
├── mcp/                    # Core MCP package (modular, reusable)
│   ├── __init__.py
│   ├── gateway.py          # Gateway base class
│   ├── middleware.py       # Tracing middleware
│   ├── auth.py             # Authentication handlers
│   ├── errors.py           # Error handling
│   └── models.py            # Pydantic models
├── gateway/                 # FastAPI application
│   ├── main.py             # FastAPI app entry point
│   └── config.py           # Configuration management
├── inspector/               # Next.js web application
│   ├── app/                # Next.js app directory
│   ├── components/         # React components
│   └── lib/                # Utilities
├── crm_mcp_server.py       # CRM REST API server
├── crm_mcp_server_mcp.py   # CRM MCP Server (for LLM integration)
├── mcp_config.json         # MCP client configuration example
├── MCP_SETUP.md            # MCP Server setup guide
├── pyproject.toml          # Python package config
├── requirements.txt        # Python dependencies
└── README.md               # This file

Testing

Test the Gateway

# Successful request
curl -X POST "http://localhost:8080/graphql" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer my-valid-token-123" \
     -d '{
         "query": "query { hello }",
         "operationName": "TestQuery"
     }'

# Authentication error
curl -X POST "http://localhost:8080/graphql" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "query { hello }"
     }'

Using the Inspector

1. Start the gateway and inspector
2. Open http://localhost:3000 in your browser
3. Configure an environment (default: http://localhost:8080)
4. Enter your GraphQL query
5. Add authentication token if required
6. Click "Send Request"
7. View response, correlation ID, and timing information

Development

Python Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests (when implemented)
pytest

# Format code
black .
ruff check .

Inspector Development

cd inspector
npm run dev      # Development server
npm run build    # Production build
npm run lint     # Lint code

MCP Server for LLM Integration

This project includes a Model Context Protocol (MCP) server that allows LLMs (like Claude Desktop, Cursor) to interact with the CRM system through natural language.

Quick Start

1. Install MCP SDK:

pip install git+https://github.com/modelcontextprotocol/python-sdk.git

2. Start the MCP Server:

./start_crm_mcp_mcp.sh
# or
python3 crm_mcp_server_mcp.py

3. Configure Claude Desktop or Cursor:
   • See MCP_SETUP.md for detailed instructions
   • Add the MCP server configuration pointing to crm_mcp_server_mcp.py

Available Tools

The MCP server exposes 8 tools for comprehensive CRM management:

• list_employees - List/search employees with optional filtering by department, status, or search query
• get_employee - Get detailed information about a specific employee by ID
• create_employee - Create a new employee record in the CRM system
• update_employee - Update an existing employee's information
• delete_employee - Delete an employee (soft delete - sets status to 'terminated')
• search_employees - Search for employees by name, email, position, or department
• get_employee_stats - Get statistics and analytics about employees
• get_departments - Get a list of all departments in the organization

Example Usage

Once connected to Claude Desktop or Cursor, you can use natural language:

"Show me all employees in the Engineering department"
"Create a new employee named Jane Smith in Sales"
"What are the employee statistics?"
"Search for employees with 'manager' in their title"
"Update employee emp-001's salary to 90000"

The LLM will automatically use the appropriate MCP tools to fulfill your requests.

Data Store Integration

The MCP server uses the same data store as the REST API server (crm_mcp_server.py). Both servers share the same employees_db dictionary, so changes made through one interface are visible in the other.

Documentation

For complete setup instructions, see MCP_SETUP.md.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.