feat(mcp): add MCP server with cardholder query tools and CLI integration

Author: devraj

README.md

@@ -18,6 +18,7 @@ Our Python Toolkit focuses on enhancing the developer experience (DX) around the
 - **Command Line Interface** (CLI) to build powerful pipeline-based workflows.
 - **Terminal User Interface** (TUI) for easy interactions with the Command Centre.
 - **SQL interface** query the REST API as if it were a database or interact with via an ORM.
+- **MCP Server** for AI assistants to query Gallagher Command Centre data through the Model Context Protocol.
 
 > [!NOTE]\
 > This project is **NOT** affiliated with Gallagher Security. All trademarks are the property of their respective owners.
@@ -114,6 +115,51 @@ Cammy         Albares      True         8427
 
 ```
 
+## AI Assistant Integration via MCP
+
+The toolkit includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that allows AI assistants to query Gallagher Command Centre data directly. This enables AI assistants to help with cardholder management, access control queries, and system monitoring.
+
+### Quick Start
+
+```bash
+# Start the MCP server
+gala mcp serve
+
+# Test the server functionality
+gala mcp test
+
+# Show configuration information
+gala mcp config
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "gallagher": {
+      "command": "python",
+      "args": ["-m", "gallagher.mcp.server"],
+      "env": {
+        "GACC_API_KEY": "your-gallagher-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Available Tools
+
+- **list_cardholders** - List all cardholders in the system
+- **search_cardholders** - Search for cardholders by name or criteria
+- **get_cardholder** - Get detailed information about a specific cardholder
+- **get_cardholder_cards** - Get all cards assigned to a cardholder
+- **get_cardholder_access_groups** - Get all access groups assigned to a cardholder
+
+For detailed documentation, see [MCP Server Documentation](docs/docs/mcp.md).
+
 ## Command Centre API Notes
 
 The Gallagher API the principles of [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) which ensures that the API is self-descriptive and future proof.

docs/docs/mcp.md

@@ -0,0 +1,250 @@
+# MCP (Model Context Protocol) Server
+
+The Gallagher Command Centre toolkit includes an MCP server that exposes cardholder querying functionality through the Model Context Protocol. This allows AI assistants to query Gallagher Command Centre data directly.
+
+## Overview
+
+The MCP server provides tools for:
+
+- Listing all cardholders in the system
+- Searching for cardholders by name or other criteria
+- Getting detailed information about specific cardholders
+- Retrieving cards assigned to cardholders
+- Getting access groups assigned to cardholders
+
+## Installation
+
+The MCP dependencies are included in the main package. No additional installation is required.
+
+## Configuration
+
+### Environment Variables
+
+The MCP server requires the following environment variable:
+
+- `GACC_API_KEY`: Your Gallagher Command Centre API key
+
+### Setting up the API Key
+
+```bash
+export GACC_API_KEY="your-gallagher-api-key-here"
+```
+
+## Usage
+
+### Running the MCP Server
+
+#### Via CLI
+
+```bash
+# Start the MCP server
+gala mcp serve
+
+# Show configuration information
+gala mcp config
+
+# Test the server functionality
+gala mcp test
+```
+
+#### Direct Module Execution
+
+```bash
+python -m gallagher.mcp
+```
+
+### Claude Desktop Configuration
+
+Add the following to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "gallagher": {
+      "command": "python",
+      "args": ["-m", "gallagher.mcp.server"],
+      "env": {
+        "GACC_API_KEY": "your-gallagher-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+For other MCP clients, you can run the server directly:
+
+```bash
+export GACC_API_KEY="your-gallagher-api-key-here"
+python -m gallagher.mcp.server
+```
+
+## Available Tools
+
+### list_cardholders
+
+Lists all cardholders in the system.
+
+**Parameters:**
+
+- `limit` (integer, optional): Maximum number of cardholders to return (default: 100)
+- `skip` (integer, optional): Number of cardholders to skip for pagination (default: 0)
+
+**Example:**
+
+```json
+{
+  "name": "list_cardholders",
+  "arguments": {
+    "limit": 10
+  }
+}
+```
+
+### search_cardholders
+
+Searches for cardholders by name or other criteria.
+
+**Parameters:**
+
+- `name` (string, required): First or last name to search for
+- `description` (string, optional): Keywords to search in description
+- `division` (integer, optional): Division ID for hierarchical search
+- `authorised_only` (boolean, optional): Only return authorised cardholders (default: false)
+- `limit` (integer, optional): Maximum number of results to return (default: 100)
+- `sort` (string, optional): Sort order - "id", "name", "-id", or "-name" (default: "name")
+
+**Example:**
+
+```json
+{
+  "name": "search_cardholders",
+  "arguments": {
+    "name": "John",
+    "authorised_only": true,
+    "limit": 5
+  }
+}
+```
+
+### get_cardholder
+
+Gets detailed information about a specific cardholder.
+
+**Parameters:**
+
+- `id` (integer, required): Cardholder ID
+
+**Example:**
+
+```json
+{
+  "name": "get_cardholder",
+  "arguments": {
+    "id": 123
+  }
+}
+```
+
+### get_cardholder_cards
+
+Gets all cards assigned to a specific cardholder.
+
+**Parameters:**
+
+- `id` (integer, required): Cardholder ID
+
+**Example:**
+
+```json
+{
+  "name": "get_cardholder_cards",
+  "arguments": {
+    "id": 123
+  }
+}
+```
+
+### get_cardholder_access_groups
+
+Gets all access groups assigned to a specific cardholder.
+
+**Parameters:**
+
+- `id` (integer, required): Cardholder ID
+
+**Example:**
+
+```json
+{
+  "name": "get_cardholder_access_groups",
+  "arguments": {
+    "id": 123
+  }
+}
+```
+
+## Example Usage
+
+Here's an example of how to use the MCP server programmatically:
+
+```python
+import asyncio
+from gallagher.mcp.server import GallagherMCPServer
+
+async def main():
+    server = GallagherMCPServer()
+
+    # List cardholders
+    result = await server._list_cardholders({"limit": 5})
+    print(result.content[0].text)
+
+    # Search for cardholders
+    result = await server._search_cardholders({
+        "name": "John",
+        "authorised_only": True
+    })
+    print(result.content[0].text)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+The MCP server handles various error conditions:
+
+- **Authentication Error**: Occurs when the API key is invalid or missing
+- **Not Found Error**: Occurs when a requested resource doesn't exist
+- **Network Error**: Occurs when there are connectivity issues
+
+All errors are returned as structured error responses with descriptive messages.
+
+## Security Considerations
+
+- The API key should be kept secure and not shared
+- The server runs on stdio by default, which is secure for local use
+- Consider using environment variables for API key storage
+- The server only provides read access to cardholder data
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Error**: Ensure the `GACC_API_KEY` environment variable is set correctly
+2. **Import Error**: Make sure all dependencies are installed
+3. **Network Error**: Check your network connection and Gallagher Command Centre accessibility
+
+### Testing
+
+Use the built-in test command to verify functionality:
+
+```bash
+gala mcp test
+```
+
+This will test basic connectivity and cardholder operations.
+
+## Development
+
+The MCP server is built using the official MCP Python SDK and integrates with the existing Gallagher Command Centre API client. The server follows the MCP specification and provides a clean interface for AI assistants to query cardholder data.