warchi-mcp

Remote Model Context Protocol server for wArchi. It exposes architectural models, diagrams, nodes, and links as MCP tools over Streamable HTTP, authenticated with personal API keys created in the wArchi profile.

Русская версия: README.ru.md

The project is built with Kotlin + Spring Boot and Spring AI MCP. It has no database of its own: API keys and authorization live in arepos-server; this service only exchanges keys for short-lived JWTs and proxies curated tool calls to the REST API.

Features

• Remote MCP server (Streamable HTTP) for Cursor and other MCP clients
• Personal API key auth (warchi_ak_…) with mode=all (global scopes) or mode=grants (per-model read/write)
• One key per agent — mixed model rights via grants, not multiple secrets
• Short-lived JWT exchange (tokenType=mcp_access) — keys are not sent on every REST call
• Curated read/write tools for models, diagrams, nodes, links, and notation summaries
• Structured tool errors for LOCKED_BY_OTHER, BATCH_SAVE_CONFLICT, missing_scope, model_not_allowed
• Health endpoint via Spring Actuator
• Dockerfile for container deployment

Tech Stack

• Kotlin 2.2.x
• Spring Boot 3.5.x
• Spring AI 1.1.x (spring-ai-starter-mcp-server-webmvc)
• JDK 24/25
• Gradle (Kotlin DSL)

Project Structure

src/main/kotlin/ru/kavader/warchimcp/
  auth/       # API key request context + filter
  client/     # arepos RestClient, exchange, JWT cache
  config/     # configuration properties
  tools/      # MCP tool definitions (read/write)

src/main/resources/
  application.yaml

docs/         # auth, tools, landscape recipe documentation

Requirements

• JDK 24 or 25
• Running arepos-server with API keys support (migration 050-api-keys or later)
• Docker (optional, for image build)

Local Development

1) Configure environment

Defaults are in src/main/resources/application.yaml. See also .env.example.

Variable	Default	Description
AREPOS_BASE_URL	http://localhost:8080	Base URL of arepos-server
PORT	8090	HTTP listen port
AREPOS_CONNECT_TIMEOUT	5s	Connect timeout to arepos
AREPOS_READ_TIMEOUT	60s	Read timeout to arepos

2) Build and run

export AREPOS_BASE_URL=http://localhost:8080
./gradlew build
./gradlew bootRun

3) Run tests

./gradlew test

Build Commands

./gradlew build       # full build + tests
./gradlew test        # unit tests
./gradlew bootJar     # fat JAR
./gradlew bootRun     # local run
docker build -t warchi-mcp:0.2.0 .

MCP Endpoint

• Protocol: Streamable HTTP (spring.ai.mcp.server.protocol=STREAMABLE)
• Default path: /mcp
• Health: GET /actuator/health

Client configuration (Cursor example)

{
  "mcpServers": {
    "warchi": {
      "url": "https://mcp.warchi.ru/mcp",
      "headers": {
        "Authorization": "Bearer warchi_ak_YOUR_KEY"
      }
    }
  }
}

Create the key in wArchi → Profile → API keys. The plaintext secret is shown once at creation.

Also accepted: X-Api-Key: warchi_ak_….

Auth Flow

1. User creates an API key in wArchi (mode=all or mode=grants with per-model scopes).
2. MCP client sends the key to warchi-mcp.
3. Server calls POST /api/v1/auth/api-keys/exchange on arepos.
4. Tools call arepos /api/v1/* with the short-lived JWT.
5. Revoking the key in Profile immediately blocks further exchanges.

Details: docs/auth.md.

Tools (v1)

Read (models:read): search_catalog, search_model, search_notation, list_models, get_model, list_diagrams, get_diagram, list_nodes, get_node, list_links, get_link, list_notations, get_notation_summary, list_wiki, get_wiki, get_node_type_hide_in_tree

Write (models:write): create_node, ensure_node, update_node, delete_node, create_link, ensure_link, update_link, delete_link, create_diagram, ensure_diagram, add_diagram_instances, update_diagram, update_model, batch_save_model, create_wiki, ensure_wiki, update_wiki, ensure_custom_properties, set_node_type_hide_in_tree

Tool catalogue: docs/tools.md.
Landscape happy-path: docs/landscape-recipe.md.

Kubernetes (local / cluster)

# lint
./scripts/helmCheck.sh

# build image + helm upgrade into namespace arch
SKIP_CONFIRM=true ./scripts/deploy.sh

# point at arepos in-cluster (default)
# AREPOS_BASE_URL=http://arepos-server:8080 SKIP_CONFIRM=true ./scripts/deploy.sh

Chart: charts/warchi-mcp/. After deploy:

kubectl -n arch port-forward svc/warchi-mcp 8090:8090
# MCP: http://127.0.0.1:8090/mcp

Deployment

Typical production layout:

1. Deploy arepos-server with API keys enabled.
2. Deploy wArchi with Profile → API keys UI.
3. Run warchi-mcp with AREPOS_BASE_URL pointing at arepos.
4. Terminate TLS at reverse proxy / ingress (https://mcp.example.com → container :8090).
5. Forward Authorization / X-Api-Key headers to the app.
6. Never log API keys or JWTs.

Docker

docker build -t warchi-mcp:0.2.0 .
docker run --rm -p 8090:8090 \
  -e AREPOS_BASE_URL=https://api.example.com \
  warchi-mcp:0.2.0

Smoke checklist

• POST /api/v1/auth/api-keys/exchange works against arepos with a test key
• MCP client can call list_models
• Revoked key → exchange returns 401
• Write without models:write on the target model → missing_scope
• mode=grants key cannot access non-granted models → model_not_allowed

Open Source Guide

• CONTRIBUTING.md / CONTRIBUTING.ru.md
• SECURITY.md / SECURITY.ru.md
• CODE_OF_CONDUCT.md / CODE_OF_CONDUCT.ru.md

Contributing

Please read CONTRIBUTING.md before opening a pull request.

Security

Please read SECURITY.md for reporting vulnerabilities.

License

This project is licensed under the MIT License.

Previously it was dual-licensed under AGPL-3.0-or-later with a commercial option; since 2026-09-24 the project is MIT.

See:

• LICENSE
• Licensing questions: nikolay@groznykh.ru