# 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?via=skill`
- **Transport:** Streamable HTTP (stateless). `POST` JSON-RPC; `GET` returns 405.
- **Protocol:** both eras are served. Send `initialize` and you negotiate
  `2025-11-25` as before. Revision `2026-07-28` has no handshake: declare each
  request with `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, `Mcp-Name` (on
  `tools/call`) and a `params._meta` envelope carrying
  `io.modelcontextprotocol/protocolVersion` and `.../clientInfo`. Headers and
  body are cross-checked and a disagreement is refused.
- **Accept header:** `application/json, text/event-stream`
- **Browser origins:** responses expose `Access-Control-Allow-Origin: *`, but the
  server-side Origin gate accepts only requests with no `Origin`,
  `https://santismm.com`, `https://www.santismm.com`, and localhost/127.0.0.1
  origins used by local development tools. Other browser origins receive 403.
  `OPTIONS` preflight returns 204 for allowed origins and permits
  `Mcp-Protocol-Version`, `Mcp-Method` and `Mcp-Name`.
- **Server info:** `{ "name": "santismm-knowledge", "version": "0.5.0" }`
- **Human docs:** `https://santismm.com/en/mcp`

### Tools (30)

| Tool | Args | Returns |
| --- | --- | --- |
| `get_overview` | — | Domains + counts. Best first call. |
| `search_all` | `query`, `surfaces?`, `limit_per_surface?`, `locale?` | Ranked router across core, Articles, Labs and claims; every hit names its `suggested_tool`. |
| `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). Translated per chapter; 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 translated per chapter; `requested_locale` / `resolved_locale` / `fallback` state exactly what came back. |
| `search` | `query`, `domains?`, `limit?`, `locale?` | **Ranked** search across all domains *and* the handbook. |
| `list_articles` | `locale?` | Every first-party essay, optionally filtered to en/es/pt. |
| `get_article` | `slug` | One complete essay with clean body, metadata and canonical URL. |
| `search_articles` | `query`, `locale?`, `limit?` | Ranked, accent-insensitive full-text search over first-party essays. |
| `list_labs` | `kind?` | Every first-party Lab with inputs, outputs, assumptions and execution URL where available. |
| `get_lab` | `slug` | One Lab's complete methodology, formulas, assumptions and related content. |
| `calculate_agent_economics` | `monthlyVolume`, `manualMinutes`, `hourlyCost`, `inputTokens`, `outputTokens`, `inputPrice`, `outputPrice`, `toolCost`, `retryRate`, `successRate`, `reviewRate`, `reviewMinutes`, `reworkMinutes` | Versioned cost, savings, ROI, successful outcomes and break-even result. |
| `calculate_evaluation_sample_size` | `failureRate`, `confidence`, `margin`, `population` | Versioned detection and estimation sample sizes, plus zero-failure probability. |
| `calculate_human_supervision_capacity` | `volume`, `sample`, `reviewMinutes`, `escalationRate`, `escalationMinutes`, `workdays`, `hoursDay`, `utilization`, `reviewers`, `hourlyCost` | Versioned FTE, headroom, backlog, sustainable volume and cost result. |
| `get_related` | `domain`, `slug`, `locale?` | Graph neighbours (outgoing + incoming) with edge types. |
| `list_claims` | `claim_type?`, `locale?` | Load-bearing claims with epistemic type, confidence and supported units. |
| `get_claim` | `id`, `locale?` | One claim with sources, limits and falsification condition. |
| `list_homeric_places` | `locale?` | Homeric Atlas places with identification class and confidence rubric. |
| `get_homeric_place` | `slug`, `locale?` | One place with competing identifications, coordinates and sources. |
| `list_homeric_episodes` | `locale?` | Iliad and Odyssey episodes in reading order. |
| `get_homeric_episode` | `slug`, `locale?` | One episode with passages, theories, rubric and sources. |
| `list_homeric_routes` | `locale?` | Reconstructed itineraries and rival variants. |
| `get_homeric_route` | `slug`, `locale?` | One route with ordered stops, hypotheses and sources. |

`locale` ∈ `en` (default) · `es` · `pt` · `fr` · `de` · `ja` · `zh`.
Federated Articles still publish en/es/pt, and Lab calculator result prose
falls back explicitly to English for the four newer site locales. `domains` ⊆
`["knowledge","patterns","architectures","governance","handbook"]` (omit it
to include every domain).

### Search behaviour

- **Multilingual:** all seven core locales are indexed, so a query matches its
  localized content regardless of the response `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`.
- **Cross-surface routing:** `search_all` adds `surface`, `source_score`,
  `rank_within_surface` and `suggested_tool`. A temporarily unavailable remote
  surface is reported without suppressing the results from healthy surfaces.

### 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?via=skill"
    }
  }
}
```

## 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` | Taxonomy of 24 real AI agents + governance-risk model, seven-locale notes. Six single-valued axes form the comparable vector **A·T·D·M·L·I**; action surfaces (**S**) are a separate multi-valued dimension, not a seventh axis, and sit outside the vector |

## Discovery files

| File | Use |
| --- | --- |
| `/llms.txt` | Machine-friendly site map (llmstxt.org convention) |
| `/llms-full.txt` | The full core knowledge corpus with provenance; links to federated first-party corpora |
| `/ai-index.json` | Master JSON manifest: core APIs, MCP, skill, Library catalogue, Labs catalogue and every first-party discovery surface |
| `/sitemap.xml` | All indexable URLs, per locale, with `lastmod` |
| `/robots.txt` | Explicitly allows AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) |
| `https://articles.santismm.com/llms-full.txt` | Full first-party essay bodies, languages and canonical metadata |
| `https://articles.santismm.com/ai-index.json` | Article catalogue, translations, feeds and discovery |
| `https://articles.santismm.com/api/articles.json` | Structured full-text Article corpus; one essay at `/api/articles/{slug}.json` |
| `https://labs.santismm.com/llms-full.txt` | Lab inputs, outputs, formulas, assumptions and limits |
| `https://labs.santismm.com/api/labs` | CORS-open structured Lab catalogue; detail at `/api/labs/{slug}` |
| `https://labs.santismm.com/api/calculate/{slug}` | `POST` executable calculator for the three calculator Labs; returns versioned inputs, results, units, warnings and citation metadata |
| `https://labs.santismm.com/openapi.json` | OpenAPI 3.1 contract for the Lab API |

## 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`. Citable content-unit
results carry that field; discovery, aggregate and claim-registry responses use
their stable endpoint or identifier instead.

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