Docs / reference / mcp

MCP tool schemas

The 5 tools @skill-wiki/mcp-server-core exposes. Schemas registered via the MCP SDK on boot.

prime_query

Search ranked atoms by intent + budget.

Input:
{
  "scope":          string,           // optional, e.g. "focus:cta"
  "tags":           string[],          // optional, multi-axis tags
  "level":          "summary" | "core" | "full",
  "budget_tokens":  number,            // optional cap; default 1200
  "kinds":          string[],          // optional kind filter
  "exclude_ids":    string[]           // optional anti-list
}

Output:
{
  "hits": [
    {
      "id":          string,           // "@scope/kind-name"
      "kind":        string,
      "tokens":      number,           // for the requested level
      "path":        string,           // file path the agent should Read
      "explanation": string            // human-readable rank reasoning
    }
  ],
  "total_tokens": number
}

prime_resolve

Brief → ranked atoms (calls L1 + L2 + L3 internally).

Input:
{
  "brief":      string,                // free-text task
  "max_tokens": number,                // optional, default 1500
  "domain":     string                 // optional override
}

Output:
{
  "intent":     IntentObject,          // L1 output (domain-shape)
  "hits":       Hit[],                  // L2 retrieval
  "contract":   {                       // L3 contract resolution
    "must_include": string[],
    "must_avoid":   string[]
  },
  "total_tokens": number
}

prime_intent

Brief → IntentObject (L1 only — useful for testing classifiers).

Input:
{
  "brief": string,
  "domain": string
}

Output: IntentObject  // domain-defined shape (per domain.yaml)

prime_validate

Generated artifact + atom set → verdict (L5).

Input:
{
  "artifact":  string,                  // generated output
  "atom_set":  string[],                // atom ids that contributed
  "validators": string[]                // optional; default: all from domain.yaml
}

Output:
{
  "ok": boolean,
  "fixes": [
    {
      "validator":  string,
      "severity":   "warning" | "error",
      "message":    string,
      "suggestion": string                // optional
    }
  ]
}

prime_compile

Compile a single .prime source on the fly. Useful for testing.

Input:
{
  "source": string,                     // .prime file content
  "deep":   boolean                     // include L2 (default false)
}

Output:
{
  "ok":            boolean,
  "diagnostics":   Diagnostic[],
  "compiled":      {
    "atom_yaml":   object,              // parsed atom.yaml
    "graph_yaml":  object,              // parsed graph.yaml
    "chunks":      {
      "summary":   string,
      "core":      string,
      "full":      string
    }
  } | null
}

Common types

type Hit = {
  id: string,
  kind: string,
  tokens: number,
  path: string,
  explanation: string
};

type Diagnostic = {
  level: "error" | "warning" | "info",
  layer: "L1" | "L2" | "L3",
  atom: string,
  message: string,
  hint?: string,
  source?: { file: string, line: number }
};

Versioning

Tool schemas are part of the protocol surface. Breaking changes ship as a major version of @skill-wiki/mcp-server-core; non-breaking additions ship as minor.