Metadata-Version: 2.4
Name: mcp-kanidm
Version: 0.1.0
Summary: MCP server for Kanidm Identity Management using FastMCP
Requires-Python: >=3.12
Requires-Dist: fastmcp<4.0,>=2.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Kanidm MCP Server (mcp-kanidm)

A professional Model Context Protocol (MCP) server for managing an advanced Kanidm deployment. Built completely asynchronously leveraging `httpx` and `FastMCP`.

This server is designed to work via the Kanidm REST v1 API using Service Accounts to keep your intelligent agents sandboxed and robust (eliminating standard CLI shell constraints).

## Features

Provides the following MCP tools for Identity and Access Management in Kanidm:

- `list_users`: Queries validated user identities with simple search filters.
- `get_user_details`: Extends deep query capabilities into PII attributes and precise access windows (requires an appropriate service account assigned).
- `reset_password_intent`: Generates a credential update intent token for help-desking scenarios securely (the AI agent will never directly reset nor touch user passwords directly).
- `delete_user`: Manages robust termination via a **Human-in-the-Loop** (HITL) prompt (`ctx.elicit()`) guaranteeing a person grants affirmative consent ahead of any destructive REST operation.

## Installation and Usage

To install or run this server dynamically within any compatible framework (Claude Desktop, etc.), you can run it via `uvx` dynamically or install via Python global packages using `uv`.

### Autenticación: Cómo obtener el KANIDM_TOKEN

**Importante:** Nunca debes configurar el agente MCP utilizando tu cuenta principal de `admin`. Para mantener la seguridad, aislar los privilegios y garantizar un rastro de auditoría claro, debes usar una **Cuenta de Servicio** (Service Account).

Sigue estos 3 pasos usando la CLI de Kanidm:

1. **Crear una cuenta de servicio** para esta integración (por ejemplo, llamada `mcp-agent`):
   ```bash
   kanidm service-account create mcp-agent "MCP Server Agent"
   ```

2. **Asignarle los privilegios correctos**. Añade esta cuenta al grupo adecuado, como `idm_people_admins` (para gestión completa de usuarios) o `idm_service_desk` (para tareas de soporte):
   ```bash
   kanidm group add-members idm_people_admins mcp-agent
   ```

3. **Generar un API Token**:
   ```bash
   kanidm service-account api-token generate mcp-agent --name mcp-token
   ```
El comando te devolverá una larga cadena. Ese es tu `KANIDM_TOKEN`.

### Execution Environment

To authenticate safely against Kanidm instances, configure your agent to inject these environmental variables securely:
* `KANIDM_URL`: Base URI of the target Kanidm system (e.g. `https://kanidm.mydomain.local`)
* `KANIDM_TOKEN`: The API Token generated for your Service Account in the previous step.

### Configuring the Agent (e.g. Claude Desktop)

In your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kanidm-server": {
      "command": "uvx",
      "args": [
        "mcp-kanidm"
      ],
      "env": {
        "KANIDM_URL": "https://idm.company.private",
        "KANIDM_TOKEN": "YOUR-SERVICE-ACCOUNT-TOKEN"
      }
    }
  }
}
```

*Note: For testing inside enterprise proxies with strict self-signed cert blocks, run the uv instances with the necessary proxy fallback arguments (`--allow-insecure-host=...`).*

### Local Development

1. Run `uv sync --all-groups` to install code, documentation tools, and dev dependencies fully.
2. Initialize pre-commits to automatically check your code syntax before commits: `uv run pre-commit install`
3. Run `uv run mcp-kanidm` to launch the STDIO pipeline manually.

*Note: For testing inside enterprise proxies with strict self-signed cert blocks, run the uv instances with the necessary proxy fallback arguments (`--allow-insecure-host=files.pythonhosted.org --allow-insecure-host=pypi.org`).*
