# identity-mcp — MCP de Identidad y Personas

Servidor MCP institucional que centraliza el acceso a la identidad, los
perfiles institucionales y los datos básicos de las personas, como primer
componente de un catálogo de MCP reutilizable por distintos agentes de IA
(Microsoft Copilot, Claude y otros compatibles con Model Context Protocol).

📄 Diseño completo: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)

## Estado actual del proyecto

> 🚧 **Etapa: bootstrap.** Este repositorio contiene únicamente la
> estructura de carpetas, la configuración del proyecto y archivos
> placeholder. **No hay lógica de negocio, tools, servicios, repositorios
> ni autenticación implementados todavía.** El servidor arranca pero no
> expone ninguna herramienta.

Próximas etapas (ver `docs/ARCHITECTURE.md` §31 Roadmap):
1. Construcción del dominio (`app/domain/`) con sus pruebas unitarias.
2. Definición de los puertos (`app/repositories/`).
3. Primer adaptador de infraestructura.
4. Servicios de aplicación, tools y su registro en `server.py`.

## Requisitos

- Python **3.12** o superior.
- (Para etapas posteriores) Redis, accesible según `RATE_LIMIT_BACKEND_URL` /
  caché (§25, §26 de `ARCHITECTURE.md`) — no es necesario para este
  bootstrap.

## Instalación

```bash
# 1. Crear y activar un entorno virtual
python3.12 -m venv .venv
source .venv/bin/activate      # En Windows: .venv\Scripts\activate

# 2. Instalar el proyecto en modo editable, con dependencias de desarrollo
pip install -e ".[dev]"

# 3. Copiar la plantilla de variables de entorno
cp .env.example .env
# Completar .env con valores reales cuando corresponda (no se usa todavía
# en esta etapa: app/config/settings.py es un placeholder).
```

## Ejecutar el servidor (bootstrap)

```bash
python server.py
```

Esto inicializa un servidor **FastMCP vacío**, sin herramientas
registradas — sirve únicamente para verificar que el proyecto compila y
arranca correctamente en esta etapa. La configuración de transporte real
(Streamable HTTP + OAuth 2.1, ver §5.3 de `ARCHITECTURE.md`), los health
checks (§23) y el registro de tools se incorporan en etapas posteriores.

## Pruebas

```bash
pytest
```

En esta etapa no hay pruebas todavía (no hay comportamiento que probar).
La estructura de `tests/unit/`, `tests/contract/` y `tests/integration/`
ya está creada conforme a §15 de `ARCHITECTURE.md`.

## Calidad de código

```bash
ruff check .        # lint
ruff format .       # formato
mypy app            # tipado estático
```

## Estructura del proyecto

Ver la estructura completa y la justificación de cada carpeta en
[`docs/ARCHITECTURE.md` §6](docs/ARCHITECTURE.md#6-estructura-de-carpetas).
En resumen:

| Carpeta | Contenido |
|---|---|
| `app/tools/` | Capa de transporte MCP (una tool por archivo) |
| `app/services/` | Casos de uso (capa de aplicación) |
| `app/domain/` | Entidades, value objects y excepciones de negocio |
| `app/repositories/` | Puertos (interfaces) que el dominio necesita |
| `app/infrastructure/` | Adaptadores (Microsoft Graph, Sistema de Personas, resiliencia) |
| `app/auth/` | Autenticación/autorización entrante y saliente |
| `app/observability/`, `app/consumption/`, `app/cache/`, `app/health/` | Aspectos transversales (§22–§26) |
| `app/config/`, `app/logging/`, `app/exceptions/`, `app/models/` | Configuración, logging/auditoría, errores y DTOs |
| `tests/` | Pruebas unitarias, de contrato y de integración |
| `docs/` | Documentación del proyecto (arquitectura, ADRs, guías) |

## Documentación relacionada

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — diseño completo, decisiones y justificaciones.
- `docs/adr/` — Architecture Decision Records (se completan al aprobar cada decisión).
- `docs/ADDING_A_TOOL.md` — guía para agregar una herramienta nueva (a redactar).
- `docs/TOOL_REGISTRY.md` — inventario de tools con owner y estado de ciclo de vida (a redactar).
- `docs/CATALOG_ENTRY.md` — metadata de este MCP para el catálogo institucional (a redactar).