Concepts

MCP Server & APM

Model Context Protocol Server

Ananke exposes a governed engineering intelligence surface via MCP, allowing any compatible IDE or agent to query specifications, architecture, code graph, policy, and evidence.

flowchart LR
    COPILOT["GitHub Copilot"]
    Q["Amazon Q"]
    KIRO["Kiro"]
    LOCAL["Local Agent"]
    MCP["🔌 MCP Server"]
    ANANKE["⚖️ Ananke Plexus"]

    COPILOT --> MCP
    Q --> MCP
    KIRO --> MCP
    LOCAL --> MCP
    MCP --> ANANKE

Starting the MCP server

# Read-only surface (safe for any agent)
ananke serve-mcp

# HTTP transport
ananke serve-mcp --transport http --port 8765 --token my-secret

# With mutation tools enabled (requires explicit opt-in)
ananke serve-mcp --allow-mutations

Default transport is stdio (for IDE integration). HTTP transport binds to loopback only by default.

Connecting an MCP client

serve-mcp speaks the Model Context Protocol (JSON-RPC 2.0), protocol versions 2025-06-18, 2025-03-26 and 2024-11-05. Any MCP client can use it: VS Code / GitHub Copilot, Claude Code, Kiro, or the official SDKs. Tools come with input schemas and read-only or destructive annotations. Tool failures return isError: true with the details. Mutation tools are listed and callable only with --allow-mutations.

// .vscode/mcp.json (GitHub Copilot)
{ "servers": { "ananke": { "type": "stdio", "command": "ananke", "args": ["serve-mcp", "--project", "${workspaceFolder}"] } } }

# Claude Code
claude mcp add ananke -- ananke serve-mcp --project .

# Python, with the official SDK (pip install "ananke-plexus[mcp]")
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async with stdio_client(StdioServerParameters(command="ananke", args=["serve-mcp"])) as (r, w), ClientSession(r, w) as s:
    await s.initialize()
    tools = await s.list_tools()
    impact = await s.call_tool("ananke.graph.impact", {"changed_files": ["src/app/users.py"]})

The original line protocol ({"action": "tools.list"}, {"action": "tools.call", "tool": …, "args": …}) still works for existing scripts. A message is treated as MCP whenever it carries "jsonrpc".

Read-only tools

Registry tools (read-only)

Agents discover skills and agents through the same registry the CLI uses. These tools never mutate the registry and are available without --allow-mutations.

Mutation tools (requires --allow-mutations)

MCP resources

Dynamic resource URIs expose live data from the workspace:

ananke://project/status        — effective config
ananke://architecture/system   — CALM document
ananke://spec/index            — list of specs
ananke://spec/PROJ-101         — spec artifact files
ananke://graph/snapshot        — latest code graph
ananke://policy/index          — active policy packs
ananke://policy/baseline       — specific pack content
ananke://evidence/index        — list of evidence runs
ananke://run/<id>/evidence     — specific run manifest
ananke://run/index             — list of all runs
ananke://registry/skills       — registered skills (read-only)
ananke://registry/agents       — registered agents (read-only)

MCP prompts

APM — Agent Package Manager

APM treats agent capabilities as supply-chain artifacts with provenance, permissions, and lockfiles.

flowchart LR
    DISCOVER["🔍 Discover"] --> INSTALL["📦 Install"]
    INSTALL --> VERIFY["🛡️ Verify"]
    VERIFY --> ACTIVATE["✅ Activate"]
    ACTIVATE --> EXECUTE["🤖 Execute"]
    EXECUTE --> AUDIT["🧾 Audit"]

Registry-backed APM

APM is the package-manager UX over the Skill & Agent Registry. Besides the legacy local-directory flow below, it resolves, installs and activates registry versions:

apm search graph
apm install core/graph-review@^1 --activate     # resolves the dependency graph
apm info core/graph-review
apm lock && apm upgrade --dry-run
apm link ../dev-copy && apm unlink core/graph-review
apm publish ./skills/graph-review --dry-run

Installed layout: .ananke/skills/installed/<ns>.<name>@<version>/; activation state is recorded in .ananke/activation.toml, and apm.lock entries carry origin = "registry" (or registry-dependency). The APM sandbox blocks skills from reading .ananke/secrets/** and config.local.toml.

Package types

• skill — reusable agent capability
• prompt-pack — curated prompts
• policy-pack — governance rules
• evaluator — evaluation rubrics
• workflow — execution templates
• tool-adapter — external tool integration
• bundle — collection of the above

Installing skills

# Install from local directory
apm install --source ./my-skill/

# List installed skills
apm list

# Inspect a skill
apm info my-skill

# Audit a skill's permissions
apm audit my-skill

# Check sandbox permissions
apm sandbox-check my-skill

# Activate for use
apm activate my-skill

# Verify integrity
apm verify my-skill

Skill manifest

[skill]
name = "graph-reviewer"
version = "1.2.0"
description = "Graph-aware impact review."
license = "MIT"

[compatibility]
ananke = ">=0.5,<1"
skill_api = "1"

[permissions]
filesystem_read = ["src/**", "tests/**", ".ananke/**"]
filesystem_write = [".ananke/evidence/**"]
network = []
shell = ["ananke graph *"]

[entrypoints]
instructions = "SKILL.md"

[provenance]
source = "github"
repository = "org/awesome-skills"
revision = "<sha>"

APM lockfile

apm.lock records exact resolved state:

• Resolved version and digest
• Source and source revision
• Transitive bundle members
• Permission hash
• License
• Install timestamp

Sandbox enforcement

Untrusted skills cannot:

• Access .ananke/secrets/** or config.local.toml
• Run blocked shell patterns (git *, curl *, rm -rf*, etc.)
• Write outside declared filesystem_write globs
• Access hosts not in network allowlist

Importing from GitHub Awesome Copilot

apm import-copilot --path ./path/to/copilot-skills/

Preserves SKILL.md, records upstream commit SHA, infers permissions conservatively, requires explicit activation for executable assets.

Bundle management

# Export a bundle of installed skills
apm bundle export --name skill-a --name skill-b --output ./release.tar.gz

# List bundle members
apm bundle list --bundle ./release.tar.gz

# Install from a bundle
apm bundle install --bundle ./release.tar.gz

Edit this page on GitHub ↗