Metadata-Version: 2.4
Name: mcp-eregistrations
Version: 1.27.0
Summary: MCP servers for eRegistrations platform (BPA + GDB + Keycloak + SmartLink)
Project-URL: Homepage, https://github.com/UNCTAD-eRegistrations/MCP_eRegistrations
Project-URL: Repository, https://github.com/UNCTAD-eRegistrations/MCP_eRegistrations
Project-URL: Documentation, https://github.com/UNCTAD-eRegistrations/MCP_eRegistrations#readme
Author-email: Moulay Mehdi Benmoumen <benmoumen@gmail.com>
Maintainer: UNCTAD Business Facilitation Section
License: Proprietary - UNCTAD/DIAE/Business Facilitation Section
License-File: LICENSE
Keywords: ai,bpa,claude,eregistrations,govtech,mcp,unctad
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Groupware
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: fastmcp<4,>=3.1.1
Requires-Dist: httpx
Requires-Dist: keyring>=25.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Requires-Dist: pyyaml
Description-Content-Type: text/markdown

# MCP eRegistrations

**AI-powered administration for eRegistrations platforms.**

A monorepo of six MCP servers that let Claude (and any MCP-compatible client) manage service design, runtime data, databases, identity, translations, and logs on eRegistrations deployments through natural language.

```
You: Scan the Jamaica service abc-123 for config issues
Claude: Found 144 issues — 67 orphaned effects (HIGH), 18 orphaned determinants (HIGH), 33 translation issues...

You: Fix the high-severity ones
Claude: Phase 1: Delete 67 orphaned effects. Phase 2: Delete 18 determinants. Proceed? [waits]
```

Each write operation is audited with per-instance rollback state.

## Packages

| Package                            | Entry point                         | Scope                                           | Tools |
| ---------------------------------- | ----------------------------------- | ----------------------------------------------- | ----- |
| `mcp_eregistrations_bpa`           | `mcp-eregistrations-bpa`            | Service design (read + write)                   | ~176  |
| `mcp_eregistrations_gdb`           | `mcp-eregistrations-gdb`            | Generic DB builder (read + write)               | ~63   |
| `mcp_eregistrations_keycloak`      | `mcp-eregistrations-keycloak`       | IAM admin (read + write)                        | ~51   |
| `mcp_eregistrations_ds`            | `mcp-eregistrations-ds`             | Display System / runtime monitoring             | ~45   |
| `mcp_eregistrations_translations`  | `mcp-eregistrations-translations`   | Translation authoring + governance (read + write) | 22  |
| `mcp_eregistrations_graylog`       | `mcp-eregistrations-graylog`        | Log search                                      | ~6    |

Common helpers live in `mcp_eregistrations_common/` (instance profiles, shared auth, config resolution).

For tool-level reference, see the per-package `CLAUDE.md` inside `src/mcp_eregistrations_*/`.

## Installation

### Plugin marketplace (recommended)

```bash
claude plugins marketplace add unctad-digital-government
claude plugins install bpa-mcp@unctad-digital-government           # Service design
claude plugins install gdb-mcp@unctad-digital-government           # Databases
claude plugins install keycloak-mcp@unctad-digital-government      # IAM
claude plugins install ds-mcp@unctad-digital-government            # Runtime monitoring
claude plugins install translations-mcp@unctad-digital-government  # Translations (authoring + governance)
claude plugins install graylog-mcp@unctad-digital-government       # Logs
```

Restart Claude Code, then register your instances:

```
/bpa-mcp:install              # walks you through adding your first profile
/bpa-mcp:login jamaica        # authenticate once, shared across all servers
```

Update with `claude plugins marketplace update unctad-digital-government` then reinstall — a marketplace bump alone does not refresh already-installed plugins.

### Direct (`uvx`)

```bash
claude mcp add --scope user --transport stdio BPA-jamaica \
  -- uvx --from mcp-eregistrations@latest mcp-eregistrations-bpa
```

Then register the instance at runtime — environment variables are only used to bootstrap the *default* instance; all other profiles are stored in `~/.config/mcp-eregistrations-bpa/profiles.json` and registered via the `instance_add` tool.

### Other MCP clients

For OpenCode, the config schema and keys differ from Claude Code's. See [`INSTALL-OPENCODE.md`](INSTALL-OPENCODE.md) for the `opencode.json` block, a ready-to-paste install prompt, and the schema differences you need to know.

## Multi-instance, shared auth

One server process can target any number of eRegistrations instances. Every tool accepts an optional `instance` parameter:

```
You: List services in Nigeria
Claude: [service_list(instance="nigeria")]

You: Same thing in Jamaica
Claude: [service_list(instance="jamaica")]
```

Profiles hold their own BPA URL, Keycloak (or CAS) settings, token store, audit log, and rollback state. Credentials saved via `auth_login` are reused silently in future sessions — and shared across the BPA, DS, and GDB servers via the OS keyring.

Auth providers, auto-detected from the profile:

| Provider   | When                                                 |
| ---------- | ---------------------------------------------------- |
| Keycloak   | Modern deployments — OIDC + password grant (default) |
| CAS        | Legacy (e.g. Cuba test) — OAuth2 + Basic Auth        |

Keycloak password grant requires **Direct Access Grants** enabled on the client. CAS requires a registered OAuth client with redirect URI `http://127.0.0.1:8914/callback`.

## Key features

- **Audit trail** — every write goes through `audit_list` / `audit_get`; state is persisted in SQLite under each profile's data directory.
- **Rollback** — most write tools produce an audit ID that `rollback` can reverse.
- **Large-response truncation** — list tools gate output at ~50 KB and emit navigation hints instead of dumping raw JSON.
- **Conventional annotations** — every tool is tagged `READ`, `WRITE`, or `DESTRUCTIVE`; clients can enforce approval policies.
- **Arazzo workflows (BPA)** — higher-level orchestrations loaded from YAML. Available in dev checkout under `_bmad-output/arazzo-workflows/`; not shipped in the wheel.

## Development

```bash
git clone https://github.com/UNCTAD-eRegistrations/MCP_eRegistrations.git
cd MCP_eRegistrations
uv sync

uv run pytest                          # ~3600 tests, <2 min
uv run pytest tests/test_ds/ -v        # single package
uv run ruff check . && uv run ruff format .
uv run mypy src/
```

### Running a server locally

```bash
uv run mcp-eregistrations-bpa
uv run mcp-eregistrations-keycloak
# etc.
```

Then point your MCP client at the stdio command. See `src/mcp_eregistrations_*/CLAUDE.md` for instance configuration specific to each server.

### Releasing

```bash
./scripts/release.sh patch        # 1.16.8 → 1.16.9
./scripts/release.sh minor --yes  # non-interactive
```

The script runs ruff, mypy, and pytest before bumping the version, generating the changelog, and creating the GitHub release. See `RELEASING.md` for the full flow.

## Project layout

```
src/
├── mcp_eregistrations_common/         # profiles, auth, audit — shared
├── mcp_eregistrations_bpa/            # BPA (FastMCP 3)
├── mcp_eregistrations_ds/             # DS (read-only monitoring)
├── mcp_eregistrations_gdb/            # GDB (databases)
├── mcp_eregistrations_keycloak/       # Keycloak admin API
├── mcp_eregistrations_translations/   # Translations — authoring + governance
└── mcp_eregistrations_graylog/        # Graylog logs

tests/                            # pytest, mirrored per package
docs/plans/                       # design docs and implementation plans
scripts/                          # release, ci-local, audit-docstrings
```

## License

Copyright (c) 2025–2026
UN Conference on Trade and Development (UNCTAD) — Division on Investment and Enterprise — Business Facilitation Section.

All rights reserved. See [LICENSE](LICENSE).

Part of [eRegistrations](https://businessfacilitation.org).
