KAIROS MCP

<!-- kairos-lint-allow-protocol-synonyms -->

<img src="logo/kairos-mcp.svg" width="128" alt="KAIROS MCP logo" />

KAIROS MCP is a TypeScript service for storing and executing reusable protocol chains for AI agents. It exposes:

• an MCP endpoint at POST /mcp
• REST endpoints under /api/*
• a browser UI under /ui
• a CLI named kairos

Without persistent workflows, agents repeat work, lose context, and cannot follow multi-step procedures reliably. KAIROS fixes this with three core ideas (the diagrams below list every MCP tool):

• Persistent memory — store and retrieve protocol chains across sessions
• Deterministic execution — activate → forward (per layer) → reward; the server drives next_action at every step
• Agent-facing design — tool descriptions and error messages built for programmatic consumption and recovery

Protocol execution runs in a fixed order: activate (match adapters), forward (run each layer’s contract; loop), then reward (finalize the run). Use train / tune / export / delete / spaces as described in each tool’s MCP description.

Default run order — activate → forward (loop per layer) → reward:

flowchart LR
  A([activate]) --> B([forward])
  B -.-> B
  B --> D([reward])
  style A fill:#4a6fa5,stroke:#2d4a7a,color:#fff
  style B fill:#ffb74d,stroke:#f57c00,color:#333
  style D fill:#81c784,stroke:#388e3c,color:#333

Discovery and adapter lifecycle — no fixed order; follow each tool’s MCP description:

flowchart LR
  S([spaces]) --- TR([train]) --- TU([tune]) --- EX([export]) --- DL([delete])
  style S fill:#4a6fa5,stroke:#2d4a7a,color:#fff
  style TR fill:#ede7f6,stroke:#5e35b1,color:#333
  style TU fill:#fff3e0,stroke:#f57c00,color:#333
  style EX fill:#e8f5e9,stroke:#388e3c,color:#333
  style DL fill:#ffebee,stroke:#c62828,color:#333

The server generates challenge data (nonce, proof_hash, URIs); agents echo those values back exactly.

Protocol execution

Authoritative behavior for agents is defined in the MCP tool resources under src/embed-docs/tools/ (activate, forward, reward). This is an on-wire summary; follow each response’s next_action and must_obey fields in real runs.

1. activate — Provide a short query string (about 3-8 words) on every call. From choices, pick one row and obey that row’s next_action (do not mix in another URI). Typical roles: match (continue with forward on the given adapter URI), refine, create (register a new adapter with train).

2. forward — With the adapter URI from activate, call forward and omit solution on the first call for that run. Read contract and next_action. For each layer, call forward again using the layer URI from the last response (add ?execution_id=... when the server returns it) and supply a solution whose type matches contract.type. Loop until next_action tells you to call reward.

3. reward — After the last layer, call reward with the layer URI from forward (not the adapter URI unless the schema explicitly allows it), outcome (success or failure), and optional evaluator fields per the tool description.

Must always: Obey next_action verbatim. Echo server-issued nonce, proof_hash, and URIs exactly.

Must never: Invent URIs; skip layers; submit a solution whose type does not match contract.type.

For a longer narrative, see docs/architecture/workflow-full-execution.md.

What runs in this repository

The current codebase includes:

• HTTP application server — Express app for MCP, REST, auth routes, and UI
• Qdrant-backed adapter store — required for runtime
• Optional Redis cache / proof-of-work state store — enabled when REDIS_URL is set
• Optional Keycloak auth integration — browser session + Bearer JWT validation
• React UI — served from the same origin at /ui
• CLI — talks to the HTTP API

Quick start

If your agent supports installable skills, start with the guided setup below. If not, use the manual Docker path that follows.

Guided setup with the kairos-install skill

Use this when you want a guided first-time setup for Ollama, .env configuration, and the minimal local stack. The repo stores kairos-install under skills/.system/, but you still install it by name.

1. Install the setup skill:

   npx skills add debian777/kairos-mcp --skill kairos-install
   

2. Ask your agent to run kairos-install for this repo. The skill confirms each system-changing step before it installs Ollama, prepares .env, and starts the minimal Docker stack.

3. Verify the server:

   curl http://localhost:3000/health
   

4. Open the UI or MCP endpoint:

   • UI: http://localhost:3000/ui
   • MCP: http://localhost:3000/mcp
   • Metrics: http://localhost:9090/metrics

Manual minimal Docker stack

Use this when you want the smallest working server deployment without the guided skill. The default Compose profile starts Qdrant + app only.

1. Create .env at the repository root. Copy the template from Docker Compose — simple stack — Environment file, then set at least:

   • QDRANT_API_KEY
   • one embedding provider:
     • OPENAI_API_KEY, or
     • OPENAI_API_URL + OPENAI_EMBEDDING_MODEL + OPENAI_API_KEY=ollama, or
     • TEI_BASE_URL (+ optional TEI_MODEL)

2. Start the stack:

   docker compose -p kairos-mcp up -d
   

3. Verify the server:

   curl http://localhost:3000/health
   

4. Open the UI or MCP endpoint:

   • UI: http://localhost:3000/ui
   • MCP: http://localhost:3000/mcp
   • Metrics: http://localhost:9090/metrics

Optional fullstack Compose profile

Extra services (cache, DB, OIDC container) are optional and not covered as a step-by-step install in docs/install/. Keycloak / IdP configuration is your responsibility. See Infrastructure and scripts/env/.env.template. Short operator note.

docker compose -p kairos-mcp --profile fullstack up -d

If you want the repo’s full local development flow, use the documented scripts:

npm ci
npm run infra:up
npm run dev:deploy

The dev scripts default the app to port 3300 (see scripts/env/.env.template and scripts/deploy-run-env.sh). The Docker minimal stack above defaults 3000 unless you set PORT in .env. Use the same host and port in health checks, the UI, and MCP URLs.

See docs/install/README.md and CONTRIBUTING.md for the exact env variables and dev workflow.

Cursor MCP (KAIROS-DEVELOPMENT)

This repository ships .cursor/mcp.json with a streamable HTTP entry keyed KAIROS-DEVELOPMENT, aimed at local MCP on http://localhost:3300/mcp (match npm run dev:deploy when PORT=3300). If you run the minimal Compose stack without overriding PORT, point MCP at http://localhost:3000/mcp instead. Cursor may show a longer agent-visible server id (for example one ending in -KAIROS-DEVELOPMENT); see AGENTS.md and docs/install/README.md#cursor-and-mcp.

When executing over MCP, follow Protocol execution above and each tool result’s next_action. The connected server’s tool descriptions are the runtime authority if they differ from this file.

Installation options

Run the server with Docker Compose

Use the Compose quick start above. This repository ships compose.yaml, inline .env templates in the install guides under docs/install/, and the scripts used for local development and CI.

Install the CLI

Node.js 24 or later is required.

Run once without installing globally:

npx @debian777/kairos-mcp --help

Or install globally:

npm install -g @debian777/kairos-mcp
kairos --help

The CLI talks to a running KAIROS server over HTTP. See docs/CLI.md.

Add KAIROS to your agent instructions

This repo ships the kairos skill for running protocols. Use --list to see what the skills registry reports for this repo.

If you want agents to use KAIROS consistently, add a short repo rule or instruction such as:

KAIROS MCP is a Model Context Protocol server for persistent memory and deterministic adapter execution. Execute protocols in this order: activate → forward (loop per layer until next_action points to reward) → reward. Echo all server-generated hashes, nonces, and URIs exactly.

Agent skills shipped in this repo

This repository currently ships three installable skills. The primary workflow skill lives in skills/. The helper skills live in skills/.system/, but you still install them by name.

Skill	Purpose
kairos	Run KAIROS adapters
kairos-bug-report	Capture structured MCP bug reports in reports/
kairos-install	First-time local setup guidance

Install all shipped skills:

npx skills add debian777/kairos-mcp

Install one specific skill:

npx skills add debian777/kairos-mcp --skill kairos

List available skills:

npx skills add debian777/kairos-mcp --list

Popular global installs:

Agents	Command
Cursor	npx skills add debian777/kairos-mcp -y -g -a cursor
Claude Code	npx skills add debian777/kairos-mcp -y -g -a claude-code
Cursor + Claude Code	npx skills add debian777/kairos-mcp -y -g -a cursor -a claude-code
All detected agents	npx skills add debian777/kairos-mcp -y -g

More detail: skills/README.md

Helm Chart Testing

This repository includes a comprehensive npm target for testing the Helm chart, matching the GitHub Actions CI pipeline.

Quick Start

# Run complete Helm test workflow (matches GitHub Actions)
npm run test:helm

This runs scripts/test-helm.sh which provides clear progress indicators and handles all validation steps.

Test Location Recommendation

Use helm/ for chart-related tests - This follows Helm conventions and keeps tests close to the chart files:

• ✅ helm/kairos-mcp/tests/ - Chart unit tests (already exists)
• ✅ helm/kairos-mctests/ - Additional chart validation tests
• ❌ tests/ - Better suited for application code tests

What the Target Tests

The single npm run test:helm command runs the complete CI workflow:

1. Dependencies - Add repos, build chart dependencies
2. Helm Lint - Strict validation of chart structure
3. Unit Tests - helm-unittest plugin validation
4. Chart Testing - ct lint validation
5. Resource Validation - kubeconform Kubernetes schema checks

Expected Behavior

• ✅ All steps pass - Chart is ready for deployment
• ⚠️ kubeconform CRD failures - Normal for custom resources (Gateway, HTTPRoute, Keycloak, etc.)
• ❌ Other failures - Requires fixes before deployment

Tool Requirements

The target checks for required tools and provides clear installation instructions:

• chart-testing (ct): brew install chart-testing
• kubeconform: brew install kubeconform
• helm-unittest: helm plugin install https://github.com/helm-unittest/helm-unittest --version v1.0.3

The target will fail fast with clear error messages if any tools are missing, avoiding unnecessary installation attempts.

Documentation map

• Documentation index
• Install and environment
• Cursor and MCP
• CLI reference
• Architecture
• Adapter examples
• Contributing

Troubleshooting

The server does not start

Check container logs:

docker compose -p kairos-mcp logs app-prod

Also verify that required ports are free:

• minimal stack: app 3000 (or your PORT), Qdrant 6333, metrics 9090 (or your METRICS_PORT)
• repo dev scripts: app often 3300, metrics often 9390 (see .env)
• full stack adds: 6379, 5432, 8080, 9000

Health check returns 503

KAIROS only reports healthy when Qdrant is ready. Wait for Qdrant to finish starting, then retry:

curl http://localhost:3000/health

Embeddings fail on startup

Set one working embedding backend in .env:

• OpenAI: OPENAI_API_KEY
• Ollama/OpenAI-compatible: OPENAI_API_URL, OPENAI_EMBEDDING_MODEL, OPENAI_API_KEY=ollama
• TEI: TEI_BASE_URL (+ optional TEI_MODEL)

Auth-enabled development is failing

Use the fullstack env example, start the fullstack profile, and configure realms:

npm run infra:up

The CLI keeps asking for login

The CLI stores tokens per API URL. Confirm that:

• you are using the expected --url / KAIROS_API_URL
• the token is still valid
• Keycloak and the KAIROS server agree on issuer and audience

Use:

kairos token --validate

Support

• Documentation
• Issues
• Discussions

Trademark

KAIROS MCP™ and the KAIROS MCP logo are trademarks of the project owner. They are not covered by the MIT license. Forks must remove the name and logo.

See TRADEMARK.md.

License

MIT — see LICENSE.