# santismm.com — full reference

Complete catalog of the MCP tools and JSON endpoints. Load this when you need
exact tool signatures or the full endpoint list; the everyday workflow is in
`SKILL.md`.

## MCP endpoint

- **URL:** `https://santismm.com/mcp`
- **Transport:** Streamable HTTP (stateless). `POST` JSON-RPC; `GET` returns 405.
- **Accept header:** `application/json, text/event-stream`
- **CORS:** open (`Access-Control-Allow-Origin: *`), so browser-based MCP
  clients work; `OPTIONS` preflight returns 204.
- **Server info:** `{ "name": "santismm-knowledge", "version": "0.1.0" }`
- **Human docs:** `https://santismm.com/en/mcp`

### Tools (13)

| Tool | Args | Returns |
| --- | --- | --- |
| `get_overview` | — | Domains + counts. Best first call. |
| `list_knowledge` | `locale?` | All knowledge units (slug, category, title, summary, provenance). |
| `get_knowledge` | `slug`, `locale?` | One knowledge unit (full, or one-locale body). |
| `list_patterns` | `locale?` | All enterprise AI patterns. |
| `get_pattern` | `slug`, `locale?` | One pattern (problem, solution, KPIs, failure modes, lessons). |
| `list_architectures` | `locale?` | All reference architectures. |
| `get_architecture` | `slug`, `locale?` | One architecture (flow, reference scenario, KPIs, cost/scaling). |
| `list_governance` | `locale?` | All governance units. |
| `get_governance` | `slug`, `locale?` | One governance unit (scope, requirements, controls, checklist, pitfalls). |
| `list_handbook` | `locale?` | All Harness Engineering Handbook chapters (HRN-001…014). English-only: cards carry `resolved_locale` / `fallback`. |
| `get_handbook` | `id`, `locale?` | One chapter by id (`HRN-001`) or slug — full Markdown body + provenance + related ids. Body is English whatever the locale; `requested_locale` / `resolved_locale` / `fallback` state it. |
| `search` | `query`, `domains?`, `limit?`, `locale?` | **Ranked** search across all domains *and* the handbook. |
| `get_related` | `domain`, `slug`, `locale?` | Graph neighbours (outgoing + incoming) with edge types. |

`locale` ∈ `en` (default) · `es` · `pt`. `domains` ⊆
`["knowledge","patterns","architectures","governance"]` (omit it to include the
handbook in the search).

### Search behaviour

- **Multilingual:** every locale is indexed, so a Spanish or Portuguese query
  matches Spanish/Portuguese content regardless of the `locale` you request.
- **Diacritic-insensitive:** `aprobacion` == `aprobación`.
- **Tokenised & ranked:** the query is split into terms; each term scores by the
  strongest field it hits (`name` > `slug`/`id` > `summary` > `category` >
  `keyConcepts` > `tags` > `body`), and matching more of the query is rewarded,
  so multi-word queries work.
- **Explainable:** each hit returns `score`, `matchedFields` and `matchedTerms`.

### Structured output

Every tool declares an **`outputSchema`** and returns **`structuredContent`** —
validated, typed data you can consume directly, with no second `JSON.parse`.
The serialized JSON is still sent in `content[].text` for backward
compatibility, so older clients keep working unchanged.

- `list_*` / `search` → `structuredContent` = `{ count, results[] }`
  (`search` also echoes `query`). `content[].text` remains the plain array.
- `get_*` → `structuredContent` = the unit object itself.
- `get_related` → `{ unit, outgoing[], incoming[] }`.
- **Not found** → `isError: true` with no `structuredContent`.

### Card shape (list / search / graph results)

```json
{
  "domain": "patterns", "id": "…", "slug": "human-approval-gate",
  "category": "…", "name": "…", "summary": "…",
  "evidence": { "evidenceLevel": "…", "confidenceLevel": "…", "sourceType": ["…"] },
  "updated": "YYYY-MM-DD", "locale": "es",
  "canonical_url": "https://santismm.com/es/patterns/human-approval-gate",
  "api_url": "https://santismm.com/api/patterns/human-approval-gate",
  "score": 6, "matchedFields": ["name"], "matchedTerms": ["aprobacion"]
}
```

Use `canonical_url` when citing; use `api_url` to fetch the full unit over HTTP.

### Client config (for MCP clients that take a JSON config)

```json
{
  "mcpServers": {
    "santismm-knowledge": {
      "type": "http",
      "url": "https://santismm.com/mcp"
    }
  }
}
```

## Read-only JSON APIs

All are `GET`, CORS-open, cacheable, and carry a `license` field.

| Endpoint | Content |
| --- | --- |
| `/api/knowledge` · `/api/knowledge/{slug}` | Knowledge units |
| `/api/patterns` · `/api/patterns/{slug}` | Enterprise AI patterns |
| `/api/architectures` · `/api/architectures/{slug}` | Reference architectures |
| `/api/governance` · `/api/governance/{slug}` | Governance units |
| `/api/handbook` · `/api/handbook/{id}` | Harness Engineering Handbook chapters (HRN-###) — also exposed as MCP tools |
| `/api/graph.json` | Whole cross-domain graph: nodes + typed edges (`related`, `composes`, `builds_on`, `operationalized_by`, `relates_to`, `elaborates`) |
| `/api/agent-taxonomy.json` | 7-axis taxonomy of ~18 real AI agents + governance-risk model, trilingual notes. Six axes are single-valued and form the comparable vector **A·T·D·M·L·I**; the seventh, **S** (action surfaces), is multi-valued and sits outside it |

## Discovery files

| File | Use |
| --- | --- |
| `/llms.txt` | Machine-friendly site map (llmstxt.org convention) |
| `/llms-full.txt` | The full consolidated corpus with provenance |
| `/ai-index.json` | JSON manifest: discovery links, API map, and the `mcp` block (endpoint + tools) |
| `/sitemap.xml` | All indexable URLs, per locale, with `lastmod` |
| `/robots.txt` | Explicitly allows AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) |

## Provenance model (Evidence-First)

Each unit's `evidence` block:

- `evidenceLevel` ∈ `production` · `simulation` · `benchmark` ·
  `industry_observation` · `theoretical`
- `confidenceLevel` ∈ `high` · `medium` · `low`
- `sourceType[]` ⊆ `personal_experience` · `production_system` · `benchmark` ·
  `paper` · `industry_observation`

Weight claims accordingly; never upgrade a `theoretical`/`industry_observation`
unit to "verified production."

## License

Content © Santiago Santa María Morales, licensed **CC BY 4.0**
(`CC-BY-4.0`, https://creativecommons.org/licenses/by/4.0/).

Reuse it freely, including commercially and in derivative works, provided you
credit the author and link the unit's `canonical_url` — which every result
carries, so the right link never has to be guessed.

The repository's source code is MIT; this covers the corpus.