{ "operations": ["searchPolicy", "getCustomer"] } ``` --- ## Tech Stack | Layer | Technology | |---|---| | **Web framework** | Django 6.x | | **WSGI/ASGI server** | Uvicorn | | **Portal UI** | HTMX + Tailwind CSS (server-rendered) | | **HTTP client** | httpx (async) | | **SOAP/WSDL parsing** | zeep + lxml | | **OpenAPI parsing** | prance + openapi-spec-validator | | **Caching** | cachetools TTLCache | | **Encryption** | cryptography (Fernet / AES-128-CBC) | | **Database** | SQLite (MVP) → PostgreSQL (production, drop-in swap) | | **Auth tokens** | python-jose (JWT) | | **Testing** | pytest + pytest-asyncio + pytest-cov | --- ## Quick Start ### Prerequisites - Python 3.11+ - Git ### 1 — Clone and set up the environment ```bash git clone https://github.com/duvaragesh/iMCP.git cd iMCP python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate pip install -r requirements.txt ``` ### 2 — Configure environment variables ```bash cp .env.example .env ``` Edit `.env` — full variable reference: ```env # Application APP_NAME=iMCP APP_VERSION=0.1.0 DEBUG=True # Set to False in production # Database DATABASE_URL=sqlite:///./imcp.db # Swap to postgres://... for production # Cache CACHE_TTL_SECONDS=3600 # How long tool definitions are cached CACHE_MAX_SIZE=1000 # Max number of cached tool sets # Rate Limiting RATE_LIMIT_PER_MINUTE=100 # Authentication JWT_SECRET=change-me-in-production-use-strong-secret # Also used for Fernet encryption JWT_ALGORITHM=HS256 # JWKS_URL=https://your-auth-provider.com/.well-known/jwks.json # CORS CORS_ORIGINS=["http://localhost:3000","http://localhost:8000"] # Logging LOG_LEVEL=INFO # DEBUG | INFO | WARNING | ERROR LOG_FORMAT=json # Redaction — fields scrubbed from all audit logs REDACTION_PATTERNS=["password","token","secret","authorization","bearer","ssn","credit_card"] # Observability (OpenTelemetry) OTEL_ENABLED=false # OTEL_ENDPOINT=http://localhost:4318 # Health Check HEALTH_CHECK_INTERVAL_MINUTES=5 ``` > **Important:** `JWT_SECRET` is also used to derive the Fernet encryption key for stored service credentials. Use a strong random value and keep it consistent across restarts — changing it will invalidate all stored credentials. ### 3 — Initialize the database ```bash python manage.py migrate ``` ### 4 — Create a superuser (admin account) ```bash python manage.py createsuperuser ``` You will be prompted for: ``` Username: admin Email address: admin@example.com Password: •••••••• Password (again): •••••••• Superuser created successfully. ``` > This Django superuser is used to log in to the Admin Portal at `/admin/login/`. It is separate from iMCP API keys. ### 5 — Generate an iMCP API Key Log in to the portal, go to **Token Manager**, and create an API key. This key is used to: - Authenticate AI client calls to the **MCP endpoint** (`/imcp/mcp`) - Authenticate calls to the **Admin REST API** (`/imcp/admin/...`) ``` Name: my-claude-key Description: Used by Claude Code MCP client Roles: admin ``` > Copy the full key shown — **it is only displayed once**. ### 6 — Start the server ```bash python manage.py runserver # or with async/ASGI support uvicorn config.asgi:application --reload ``` ### 7 — Open the portal - Login: `http://localhost:8000/admin/login/` - Portal: `http://localhost:8000/imcp/portal/` ### 8 — Connect an AI client ```bash # Claude Code CLI claude mcp add --transport http iMCP http://localhost:8000/imcp/mcp \ --header "Authorization: Bearer " \ --scope project ``` Run `/mcp` inside Claude Code to confirm `iMCP` is listed and tools are available. --- ## Admin Portal Walkthrough ### Adding Your First Service 1. Go to **Services** in the sidebar 2. Click **+ Add Service** 3. Fill in: | Field | Description | Example | |---|---|---| | **Name** | Unique identifier | `Policy Search` | | **Spec Type** | Format of the spec | `WSDL`, `OpenAPI`, or `MCP JSON` | | **Spec Source** | URL or file upload | `http://ibmi-host/ws/PolicySearch?wsdl` | | **Category** | Grouping label | `Policy`, `Claims`, `Underwriting` | | **Auth Type** | Authentication method | `Basic`, `Bearer`, `OAuth2` | 4. Click **Save** — tools are generated and cached automatically ### Verifying Generated Tools 1. Go to **Tools** in the sidebar 2. Select your service from the filter 3. Each tool shows its name, description, input schema, and cache status 4. Click **Refresh** on any service to re-parse its spec and regenerate tools ### Testing a Tool 1. Go to **Test Console** in the sidebar 2. Select a tool from the dropdown 3. Fill in the arguments (JSON editor with schema hints) 4. Click **Run** — results show: - Normalized response - Raw upstream HTTP request/response (credentials redacted) - Correlation ID and latency ### Monitoring Health The **Status** page shows: | Metric | Description | |---|---| | Adapter health | Up / down per service | | Service reachability | Live latency probes | | Cache statistics | Hit rate, size, TTL, miss count | | Error log | Recent failures with correlation IDs | --- ## Supported Spec Types

WSDL / SOAP — IBM AS400, SAP, Oracle, Mainframe

Point iMCP at any WSDL URL or upload a `.wsdl` / `.xml` file. iMCP will: - Parse all services, ports, and operations - Extract input message types and convert XSD to JSON Schema - Handle nested complex types (policies, claims, coverage objects) - Apply operation allowlists/denylists ```bash # Register via API POST /imcp/admin/services { "name": "PolicySearch", "spec_type": "wsdl", "spec_url": "http://ibmi-host/wsservices/PolicySearch?wsdl", "auth_type": "basic", "auth_config": { "username": "svcuser", "password": "••••" } } ```

OpenAPI 2.x / 3.x — REST APIs, API Gateways

Supply an OpenAPI spec as a URL or upload a `.yaml` / `.yml` / `.json` file. iMCP will: - Resolve all `$ref` references via `prance` - Generate one tool per path + method combination - Map path, query, and request body parameters to the tool `inputSchema` - Preserve validation constraints (enums, min/max, patterns) ```bash POST /imcp/admin/services { "name": "ClaimsAPI", "spec_type": "openapi", "spec_url": "https://api.internal/claims/openapi.yaml", "auth_type": "oauth2", "auth_config": { "token_url": "https://auth.example.com/token", "client_id": "imcp-client", "client_secret": "••••", "scope": "read:claims" } } ```

MCP JSON — Simple REST, Apigee, Internal microservices

A lightweight custom format for wrapping any HTTP endpoint directly — no full WSDL or OpenAPI spec required. Ideal for quick prototyping and simple API gateway routes. - No spec file needed — describe tools directly in JSON - Supports GET / POST / PUT / DELETE - Query params and request body mapping - Default values for optional parameters - One-click template download from the portal

--- ## MCP JSON Spec Format ```json { "name": "my-service-name", "version": "1.0.0", "description": "Brief description of what this service does", "tools": [ { "name": "toolName", "description": "Describe what this tool does — this text is shown to the AI when selecting tools.", "inputSchema": { "type": "object", "properties": { "param1": { "type": "string", "description": "Description of param1", "default": "optional-default-value" }, "param2": { "type": "string", "description": "Description of param2" } }, "required": ["param1"] }, "endpoint": { "method": "GET", "baseUrl": "https://your-api-base-url.example.com", "path": "/your/api/path/", "queryParams": ["param1", "param2"] } } ] } ``` **Field reference:** | Field | Required | Description | |---|---|---| | `name` | Yes | Service identifier | | `version` | No | Version string | | `tools[].name` | Yes | Tool name exposed to AI clients | | `tools[].description` | Yes | Natural-language description for the AI | | `tools[].inputSchema` | Yes | JSON Schema for tool arguments | | `tools[].inputSchema.properties[*].default` | No | Default value applied if argument is omitted | | `tools[].endpoint.method` | Yes | HTTP method: `GET`, `POST`, `PUT`, `DELETE` | | `tools[].endpoint.baseUrl` | Yes | Base URL of the upstream API | | `tools[].endpoint.path` | Yes | Path appended to `baseUrl` | | `tools[].endpoint.queryParams` | No | Parameter names sent as query string | > **Tip:** Click **Download JSON template** in the Add/Edit Service modal (when MCP JSON is selected) to get a pre-filled template file. --- ## Authentication Types

Bearer Token — Static token

```json { "token": "your-static-bearer-token" } ``` Injected as `Authorization: Bearer ` on every upstream call.

Basic Auth — Username + Password

```json { "username": "user", "password": "pass" } ``` Encoded as `Authorization: Basic ` on every request.

Custom Headers — Arbitrary headers

```json { "headers": { "X-API-Key": "abc123", "X-Tenant": "acme-corp" } } ``` Any headers your backend requires — `X-API-Key`, `X-Tenant`, proprietary auth headers, etc.

OAuth2 Client Credentials — Auto-refreshing token

```json { "token_url": "https://auth.example.com/oauth/token", "client_id": "your-client-id", "client_secret": "your-client-secret", "scope": "read:policies" } ``` iMCP fetches a token from `token_url` using the `client_credentials` grant, **caches it for ~58 minutes**, and automatically refreshes it — completely transparent to the AI caller. **OAuth2 token flow:** ``` iMCP Executor → oauth.py (cache miss?) → Token Endpoint ↑ ↓ Token Cache ←────────── access_token ↓ Authorization: Bearer … → Upstream Service ```

--- ## API Reference ### Request Flow iMCP Request Flow

### MCP Protocol Endpoint ``` POST /imcp/mcp Content-Type: application/json Authorization: Bearer ``` **List tools:** ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` **Call a tool:** ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "searchPolicy", "arguments": { "policy-reference": "POL-20241001-001" } } } ``` ### REST Convenience Endpoints | Method | Path | Auth | Description | |---|---|---|---| | `GET` | `/imcp/health` | None | Health check | | `POST` | `/imcp/mcp/tools/list` | Bearer | List all available tools | | `POST` | `/imcp/mcp/tools/call` | Bearer | Execute a tool | ### Admin API All admin endpoints require `Authorization: Bearer `. | Method | Path | Description | |---|---|---| | `GET` | `/imcp/admin/services` | List services (filter: `category`, `spec_type`, `enabled`) | | `POST` | `/imcp/admin/services` | Create a service (JSON body or multipart file upload) | | `GET` | `/imcp/admin/services/` | Get a single service | | `PUT` | `/imcp/admin/services/` | Update a service | | `DELETE` | `/imcp/admin/services/` | Disable (soft) or hard-delete | | `POST` | `/imcp/admin/services//discover-operations` | Discover operations from the spec | | `GET` | `/imcp/admin/tools` | List cached tools for a service | | `POST` | `/imcp/admin/tools/refresh` | Regenerate tools for a service | | `POST` | `/imcp/admin/test/call` | Execute a tool via the test console | | `GET` | `/imcp/admin/status` | System status and health metrics | | `POST` | `/imcp/admin/status/run-checks` | Trigger upstream reachability checks | | `GET/POST` | `/imcp/admin/api-keys` | List or create API keys | | `DELETE` | `/imcp/admin/api-keys/` | Revoke an API key | --- ## Security Model | Layer | Mechanism | |---|---| | **Credential storage** | Fernet AES-128-CBC encryption using a key derived from `JWT_SECRET` via SHA-256. Credentials decrypted only in memory at call time — never returned by GET endpoints. | | **PII redaction** | Configurable patterns scrub `Authorization`, `token`, `password`, `client_secret`, `credentials`, and custom PII fields from all audit records. | | **Operation governance** | Per-service allowlists and denylists. Operations outside the allowlist are invisible at `tools/list` — undiscoverable and uncallable. | | **API key auth** | Keys stored as hashed values only. Never returned by any API. Instant revocation via Token Manager. | | **Audit trail** | Every call logged with `correlation_id`, actor, action, service, tool, status, latency, and redacted payload. | | **Transport** | Upstream calls use `httpx` with TLS. Portal traffic should sit behind Nginx TLS termination. | | **Rate limiting** | Configurable per-minute limit per client (in-memory; Redis-backed in production). | ### Credential Lifecycle ``` Register service (plaintext creds) ↓ Fernet encrypt → store in DB ↓ At call time: decrypt in memory → build auth header → call upstream ↓ Discard decrypted value — never logged, never returned ``` --- ## Configuration All settings are controlled via `.env` (copy from `.env.example`): | Variable | Default | Description | |---|---|---| | `APP_NAME` | `iMCP` | Application name shown in portal | | `APP_VERSION` | `0.1.0` | Version string | | `DEBUG` | `false` | Set to `false` in production | | `DATABASE_URL` | `sqlite:///./imcp.db` | Database — swap to `postgres://...` for production | | `CACHE_TTL_SECONDS` | `3600` | Tool definition cache TTL in seconds | | `CACHE_MAX_SIZE` | `1000` | Max cached tool sets | | `RATE_LIMIT_PER_MINUTE` | `100` | Max requests per minute per client | | `JWT_SECRET` | *(required)* | JWT signing key **and** Fernet encryption source — keep stable | | `JWT_ALGORITHM` | `HS256` | JWT signing algorithm | | `JWKS_URL` | *(optional)* | External JWKS URL for identity provider token validation | | `CORS_ORIGINS` | `["http://localhost:8000"]` | Allowed CORS origins (JSON array) | | `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` | | `LOG_FORMAT` | `json` | Log output format | | `REDACTION_PATTERNS` | see `.env.example` | JSON array of field names scrubbed from audit logs | | `OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing | | `OTEL_ENDPOINT` | *(optional)* | OTLP endpoint, e.g. `http://localhost:4318` | | `HEALTH_CHECK_INTERVAL_MINUTES` | `5` | How often upstream reachability checks run | ### Scaling to Production | Component | Development | Production | |---|---|---| | Database | SQLite | PostgreSQL | | Cache | In-memory TTLCache | Redis | | Deployment | Single process | 2+ replicas behind Nginx | | Rate limiting | In-memory | Redis-backed | --- ## Connecting AI Assistants ### Claude Code CLI ```bash claude mcp add --transport http iMCP http://localhost:8000/imcp/mcp \ --header "Authorization: Bearer " \ --scope project ``` Run `/mcp` in Claude Code to confirm `iMCP` is listed and tools are available. ### VS Code (MCP Extension) Add to `.vscode/mcp.json`: ```json { "servers": { "iMCP": { "type": "http", "url": "http://localhost:8000/imcp/mcp", "headers": { "Authorization": "Bearer " } } } } ```

iMCP

Installation