# IDmission Identity MCP Server

A Model Context Protocol (MCP) server that validates ID documents using the IDmission Identity API.

## Purpose

This MCP server gives Claude a secure interface for submitting ID document images to IDmission's identity verification service and returning the verification result (e.g. Approved / Denied), without ever hardcoding credentials in code.

## Features

### Current Implementation
- **`validate_id`** - Submits front (and optionally back) images of an ID document to IDmission's `validate-id` endpoint, and returns the verification result, ID number, and expiration date
- **`validate_id_match_face`** - Submits the ID document image(s) plus a selfie to IDmission's `validate-id-match-face` endpoint, and returns whether the face match was approved
- **`live_check`** - Submits a selfie image to IDmission's `live-check` endpoint, and returns whether it was approved as a genuine live capture

These can be added later using the same authentication pattern already in place.

## Prerequisites

- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (`docker mcp` command)
- IDmission API credentials: client ID, client secret, username, and password (contact your IDmission account team if you don't have these)
- A local folder containing the ID images you want to validate

## Important: File Access

This server runs inside a Docker container, which cannot see files on your Mac/PC by default. To validate an ID image, you must **mount a local folder** containing your images into the container (e.g. map `~/idmission-images` on your machine to `/images` inside the container). See the installation instructions for exactly where to configure this.

Once mounted, pass paths like `/images/front.jpg` (the *container* path, not your local path) to the `validate_id` tool.

## Installation

See the step-by-step instructions provided alongside these files.

## Usage Examples

In Claude Desktop, you can ask:
- "Validate this passport, front image at /images/passport_front.jpg, country GBR"
- "Run validate_id on /images/dl_front.jpg and /images/dl_back.jpg, id_type DL, id_country USA"
- "Validate /images/front.jpg with id_type NSP and id_country NSP" (lets IDmission auto-detect the document type and issuing country instead of specifying them)
- "Match the selfie at /images/selfie.jpg against the ID at /images/front.jpg, id_type NSP, id_country NSP"
- "Run a liveness check on /images/selfie.jpg"

## Architecture

```
Claude Desktop → MCP Gateway → IDmission MCP Server → IDmission Auth (OAuth token)
                                                     → IDmission validate-id API
                        ↓
              Docker Desktop Secrets
    (IDMISSION_CLIENT_ID, IDMISSION_CLIENT_SECRET,
     IDMISSION_USERNAME, IDMISSION_PASSWORD, IDMISSION_SCOPE)
```

## Development

### Local Testing

```bash
# Set environment variables for testing
export IDMISSION_CLIENT_ID="your-client-id"
export IDMISSION_CLIENT_SECRET="your-client-secret"
export IDMISSION_USERNAME="your-username"
export IDMISSION_PASSWORD="your-password"

# Run directly
python idmission_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python idmission_server.py
```

### Adding New Tools (e.g. live-check, validate-id-match-face)

1. Add a new `async def` function to `idmission_server.py`, reusing `get_access_token()` for auth
2. Decorate with `@mcp.tool()`
3. Use a single-line docstring and string parameter defaults (`param: str = ""`)
4. Update the catalog entry's `tools:` list with the new tool name
5. Rebuild the Docker image

## Troubleshooting

### Tools Not Appearing
- Verify the Docker image built successfully
- Check catalog and registry files
- Ensure Claude Desktop config includes the custom catalog
- Restart Claude Desktop

### "Front ID image not found" errors
- Confirm the images folder is mounted into the container
- Use the container-side path (e.g. `/images/front.jpg`), not your local machine's path

### Authentication Errors
- Verify secrets with `docker mcp secret list`
- Confirm the four required secrets are all set: `IDMISSION_CLIENT_ID`, `IDMISSION_CLIENT_SECRET`, `IDMISSION_USERNAME`, `IDMISSION_PASSWORD`
- IDmission uses the OAuth password grant — double-check the username/password are correct API credentials, not your portal login

## Security Considerations

- All credentials stored in Docker Desktop secrets, never hardcoded
- Access tokens are cached in memory only, never logged or written to disk
- Running as a non-root user inside the container
- ID images are read into memory, base64-encoded, and sent directly to IDmission — never persisted by this server
- Sensitive data (tokens, passwords, image contents) never logged

## License

MIT License