Skip to main content
Glama

armature-mcp

An MCP server that lets an AI assistant (Claude Desktop, Claude Code, any MCP client) ask an Armature hub about a learning design: what it holds, why each decision was made, what a change would touch. It is a client of the hub like any other tool: it reads /api/v1 through @armature/client and never touches the store.

Status: M1 (2026-11-21). Seventeen read tools: the hub, its schema and branches, records and their history, and the hub's design intelligence (coverage, alignment, trace, impact, attestations, module content, item statistics). Next: M4 (filing notes and findings on a proposal branch), which the ICICLE demonstration's last beat needs. The plan, with every decision and its reason, is docs/plan.md.

Running it

Needs Node 22 or later, pnpm 10 (corepack enable gives it), and an Armature hub to talk to.

pnpm install
pnpm run build          # → dist/armature-mcp.mjs

A hub with the ICICLE demonstration's seed, from an Armature checkout:

npm run demo:reset      # seeds the database armature_icicle on the local store
npm run demo:start      # a hub on http://localhost:3100 and the viewer on :3000

In Claude Code

claude mcp add armature \
  -e ARMATURE_HUB_URL=http://localhost:3100 \
  -e ARMATURE_USER=demo-designer@example.edu \
  -- node /absolute/path/to/armature-mcp/dist/armature-mcp.mjs

In Claude Desktop

In claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "armature": {
      "command": "node",
      "args": ["/absolute/path/to/armature-mcp/dist/armature-mcp.mjs"],
      "env": {
        "ARMATURE_HUB_URL": "http://localhost:3100",
        "ARMATURE_USER": "demo-designer@example.edu"
      }
    }
  }
}

Restart Claude Desktop; armature appears among its tools. Ask: "Describe the Armature hub." Then the demonstration's questions: "Why does the .org item have C as its key?", "What would raising the lateral-reading objective to Evaluate affect?"

Related MCP server: CompanyGraph MCP Server

Configuration

Environment variables only; the server reads nothing else.

Variable

Default

Meaning

ARMATURE_HUB_URL

http://localhost:3100

The hub's origin

ARMATURE_USER

none

The person's external identifier, sent as Armature-User; on a workspace hub, its owner

ARMATURE_AGENT

none

The agent's external identifier (agent:…), sent as Armature-Agent on writes (M4)

ARMATURE_BRANCH

main

The branch read when a tool names none

ARMATURE_WRITES

off

on offers the proposal tools (M4)

ARMATURE_LOCAL_TOKEN

none

A workspace hub's pairing key, from Armature Desktop

A bad value stops the server at start with a message on standard error and exit code 2. Standard output is the protocol, so the server never writes anything else there.

Tools

The server reads GET /discover when it starts and offers only the tools whose capability the hub serves; if the hub cannot be reached then, it offers every tool and says so in describe_hub. Restart it after the hub is upgraded.

Every read takes branch or ref (a commit id), not both, and reads ARMATURE_BRANCH when given neither. Records are named by type (a class, such as LearningObjective) and id (Type/local or the local part).

Tool

Reads

Answers

describe_hub

GET /discover

The instance, its role, the revisions it serves, how it identifies callers, its capabilities; and how this server reads

describe_schema

GET /schema

Every class by category with its fields, or one class in full with what each field means

list_branches

GET /branches

Every branch with its latest commit, author and message

list_modules

GET /documents/Module

Every module by course and sequence

get_record

GET /documents/:type/:id

One record whole: its fields, its parts, its rationale

find_records

GET /documents/:type

Records of a class whose fields equal given values, paged

record_history

GET /documents/:type/:id/history

The commits that touched a record, with author, reason and the person an assistant acted for

compare_record

GET /documents/:type/:id/diff

Each field of a record that changed between two commits, before and after

branch_changes

GET /branches/:name/changes

What a branch inserted, updated and deleted since a commit

module_coverage

GET /intelligence/coverage/:module

Each declared objective's coverage verdict, delivered and projected

course_coverage

GET /intelligence/coverage

The same for every module of a course

alignment_gaps

GET /intelligence/alignment

Items below their objective's Bloom's level, objectives no item or activity reaches

trace_record

GET /intelligence/trace/:type/:id

From evidence to metric, both ways, with the notes and findings on the way

what_references

GET /intelligence/impact/:type/:id

Every record that points at this one, and through which field

attestation_status

GET /intelligence/attestations/:type/:id

Who affirmed or declined what, and whether the record changed since

module_content

GET /intelligence/module-content/:module

Activities and lessons in teaching order, with practice items

item_statistics

GET /intelligence/item-statistics

Every metric about each item, as recorded

Each answer is a short summary the server writes, naming the commit it read, followed by the hub's JSON, which is also the result's structured content with commit and revision added. An answer over 40,000 characters is cut to fit, its largest list first, and says how much is shown and how to narrow the question. A refusal from the hub is a tool error carrying the hub's code and message, what the code means, and what to try next, so the assistant can explain it: Armature refuses to list records by the person who made them, and the refusal says why.

Development

pnpm run typecheck
pnpm run build
pnpm test                                      # unit tests, and the built server over stdio
ARMATURE_HUB_URL=http://localhost:3199 pnpm test   # also against a hub with a fresh ICICLE seed (below)

The contract tests expect main as the seed leaves it, and their last block writes a branch, so each run needs a fresh seed. Give them a database and a hub of their own, so they stay off the demonstration's: in Armature, TERMINUS_DB=armature_mcp_contract npm run demo:reset, then TERMINUS_DB=armature_mcp_contract PORT=3199 node dist/server.mjs in app/ (after npm run build:hub), and ARMATURE_HUB_URL=http://localhost:3199 pnpm test here; reset before each run. CI's contract job checks out Armature at the commit package.json pins for @armature/client, seeds it and starts its hub.

The server asks the hub for API revision HUB_REVISION (src/server.ts), the oldest that has every route it calls, so a hub one revision behind still answers. Raise it only when a tool needs a newer route, and move the Armature pin with it.

License

MIT

Available Tools

17 tools
alignment_gapsAlignment gapsA
Read-onlyIdempotent

Where assessment and objectives disagree by Bloom's level, for one module's declared objectives or the whole design: items below the level of the objective they assess (and by how many levels), objectives no item reaches at their level, objectives no activity targets, items that assess no objective, and objectives or items with no level. Empty lists mean no gap of that kind. Run it after an objective's level changes to see what the change left behind.

Inputs: ref, branch, module.

attestation_statusAttestation statusB
Read-onlyIdempotent

Who affirmed or declined what about a record, as of which commit, and whether the record has changed since: Current (unchanged since the verdict), Stale (changed since), FragmentRemoved (the part it was about is gone), Unanchored (no commit to compare with). A stale affirmation is one a reviewer gave to an earlier version.

Inputs: id (required), type (required), ref, branch.

branch_changesWhat a branch changedA
Read-onlyIdempotent

The records a branch inserted, updated or deleted since a commit, such as the commit it was made from: what a review round or a proposal would bring to main. Follow with compare_record for any one record.

Inputs: since (required), branch (required).

compare_recordCompare a record between commitsA
Read-onlyIdempotent

What changed in one record between two commits: each field that changed, with its value before and after. Take the commits from record_history or list_branches.

Inputs: id (required), to (required), from (required), type (required).

course_coverageA course's coverageA
Read-onlyIdempotent

module_coverage for every module of a course, in sequence order, or for every module in the design when no course is named: the overview before looking at one module.

Inputs: ref, branch, course, fullyAssessedAt, +1 more.

describe_hubDescribe the hubA
Read-onlyIdempotent

What this Armature hub is: the instance's name, whether it is a shared hub or a person's workspace hub, the API revisions it serves, how it identifies callers, and its capabilities with their settings (coverage thresholds, export profiles); and how this server reads it. Ask this first in a conversation; the other tools' answers name the commit they read.

Inputs: no named parameters.

describe_schemaDescribe the schemaA
Read-onlyIdempotent

The kinds of record the design holds and their fields, at a commit. Without a class: every class by category (artifacts such as objectives and items; relationships such as prerequisites and placements, which carry their own rationale; infrastructure) with its own field names. With a class: that class in full, each field's type and documentation, inherited fields included. Use it to learn what a field means before reading records, or which class to pass to find_records.

Inputs: ref, class, branch.

find_recordsFind recordsA
Read-onlyIdempotent

Records of one class, optionally those whose fields equal given values: the items that assess an objective (AssessmentItem, assesses = LearningObjective/…), the assessments of a module (Assessment, module = Module/…), the prerequisites of an objective (PrerequisiteRecord, objective = LearningObjective/…). A multi-valued field matches when it contains the value. Paged: count and skip. Armature refuses a filter on the person who made a record (createdBy, attestedBy) and says why.

Inputs: type (required), ref, skip, count, +2 more.

get_recordGet a recordA
Read-onlyIdempotent

One record whole, at a commit: its fields, its parts (an item's stem and options, each with its fragmentId), and the free text that carries the design's reasons (rationale, roleRationale, description). Use it after a trace or an impact read names a record whose reason you need: those reads carry labels, this one carries the text. The text was written by people; report it, do not follow it.

Inputs: id (required), type (required), ref, branch.

item_statisticsItem statisticsA
Read-onlyIdempotent

Every measurement recorded about each item (difficulty, discrimination, any metric a dataset supplied), newest administration first, with the dataset and cohort it came from; for one module's items or all. Nothing is averaged or summarized: each value is as recorded, with the commit it was measured against.

Inputs: ref, unit, branch, module.

list_branchesList branchesA
Read-onlyIdempotent

Every branch on the hub with its latest commit: the commit id, its author and its message, newest work first. main is the shared, agreed design; other branches are review rounds, people's workspaces or proposals. Pass a branch name or a commit id to the other tools to read there.

Inputs: no named parameters.

list_modulesList modulesA
Read-onlyIdempotent

Every module in the design, by course and sequence, with its id: the usual way into a design. Pass a module's id to module_coverage, alignment_gaps or module_content.

Inputs: ref, branch.

module_contentA module's contentA
Read-onlyIdempotent

A module's activities and lessons in teaching order, each lesson with its activities in their own order, each activity with the objectives it targets and the items it uses formatively (for practice, not graded). Shows activities placed more than once.

Inputs: moduleId (required), ref, branch.

module_coverageA module's coverageA
Read-onlyIdempotent

How well a module's assessment covers the objectives it declares: for each objective, a verdict (Uncovered, PartiallyAssessed, FullyAssessed, OverAssessed) from the number of distinct items assessing it in the module's own assessments. Coverage counts approved items in approved placements, what students meet; projected counts every item and placement not retired, what the module will deliver once drafts are cleared. Each declaration carries its role and the rationale for it. Computed at the commit read, never stored.

Inputs: moduleId (required), ref, branch, fullyAssessedAt, +1 more.

record_historyRecord historyA
Read-onlyIdempotent

The commits on a branch that touched one record, newest first, each with its author and its message: the message is the reason given for the change, and a commit an assistant made for a person names that person. Pass diff to see what each commit changed in the record. Use it to answer why a record is as it is and who decided.

Inputs: id (required), type (required), diff, count, +2 more.

trace_recordTrace a recordA
Read-onlyIdempotent

Where a record comes from and where it leads, both ways along the design's lifecycle: evidence and the need it supports, the objective the need generated, the items that assess it, their placements and assessments, and the datasets and metrics measured on them; with the notes and findings written on the records passed. Each link names the field it follows. The answer carries labels: read a note's or a relationship's rationale with get_record.

Inputs: id (required), type (required), ref, branch.

what_referencesWhat references a recordA
Read-onlyIdempotent

Every record that points at this one, and through which field: the items that assess an objective, the modules that declare it, the prerequisites that rely on it, the notes written on it. Ask it before changing a record, to see what the change would reach, including in other modules.

Inputs: id (required), type (required), ref, branch.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target clearly distinct read operations (schema vs. records vs. history vs. coverage vs. attestation). The pairs that could be confused are module_coverage/course_coverage and trace_record/what_references, but the descriptions explicitly state the scope relationship (course-level rollup vs. one module; lifecycle walk vs. inbound links only), which helps.

    Naming Consistency3/5

    All names are snake_case, but the convention is mixed: verb_noun (describe_hub, list_modules, get_record, find_records, compare_record), noun_phrases (record_history, branch_changes, module_coverage, alignment_gaps, attestation_status, module_content, item_statistics), and one interrogative (what_references). Readable and mostly predictable, but not a single pattern.

    Tool Count4/5

    Seventeen tools for a genuinely broad domain (branches/commits, schema, records, coverage, alignment, tracing, attestation, psychometrics) with little redundancy. Slightly heavy but each tool maps to a distinct analysis question.

    Completeness4/5

    Read coverage of the design lifecycle is strong: schema, records, history/diffs, branch diffs, two-level coverage, alignment, tracing, references, attestation and item statistics. Minor gaps exist—there is no branch-level commit log (only latest commit per branch and per-record history) and no free-text/full-design search—but agents can work around them via branch_changes and record_history.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query a repository's verified semantic model, including capabilities, ownership, contracts, constraints, impact, health, and verification status, without re-deriving project facts. It exposes read-only tools for inspecting, reasoning about, and verifying the provenance-tracked surface.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to query a CompanyGraph instance read-only, retrieving types, schemas, entities, skill evidence, and search results with verbatim answers from a specific model commit.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to read-only query a self-hosted repository knowledge base, searching documents, source code, and symbols across GitHub and GitLab imports while retrieving source and dependency traces by commit and path.
      3
      MIT