champollion-mcp-server 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.4.0 (2026-10-18) — on rails
+
+### Fixed — found by the release candidate's packaged walk (2026-10-18)
+
+- **`model_in_use` on `project_status`**: once a model is served, its try page
+  and the `champollion connect` command that puts it into an app or website
+  travel with the improve rounds' steps. The journey goes on to round 1 after
+  serving, so it never "finishes", and an agent on the rails never heard of
+  connect. The rails instructions and the agents' MCP page say what to do
+  with it (tell the person once; they run connect when they want it).
+
+- **The rails profile is the default.** `npx champollion-mcp-server` now
+  starts the six-tool rails profile (start a language project, read its
+  next step, run it, add data, try the model, explain). Every other tool is
+  in the full profile: `--profile full` or `CHAMPOLLION_MCP_PROFILE=full`.
+  A client configured for the old default adds `--profile full`.
+- **The rails tools.** `start_project` (a project folder with a place for
+  everything; a private-use code like `qaa` needs `target_name`),
+  `project_status` (THE next step, read from the project's files; with
+  `wait_seconds` it waits up to 120 s for a running step), `run_next_step`,
+  `add_data`, `try_translation` and `explain` (the rails, privacy, quality,
+  the step modes, stepping off the rails). Steps run as the same
+  `champollion` and `nmt-forge` commands a person types. The instructions
+  (`instructions-rails.md`) stay under 7,500 characters.
+- **The people decide.** `run_next_step` runs only the step `project_status`
+  just named (the step ids must match) and refuses a step only a person can
+  take, or one that is waiting. A step that asks the data's holders runs
+  only with their answers, checked against what the step asks and put
+  into the command's arguments, never a shell string; an install or training
+  step runs only with `confirmed: true`. A step that failed twice in a row
+  runs again only when the person says so (`confirmed: true`); the refusal
+  hands back its last output.
+- **Only the rails' own commands run:** `champollion`, `nmt-forge`, and
+  `uv tool install … nmt-forge` (`--python`, `--reinstall`, `--upgrade`).
+  Pipes, `;`, redirects, `$` and backticks are refused; a `#` starting a word
+  is a comment, as in a shell. Every command is a bounded process (10
+  minutes; 15 for the forge install). If `uv` is missing, the step is refused
+  with where the person installs it — the server never downloads or runs an
+  installer. When the installed `nmt-forge` is older than the rails need,
+  the tools step says both versions and offers the `--upgrade` install, for
+  the person to confirm.
+- **`add_data`** brings in spreadsheets (.xlsx, .ods, .csv), .tsv/.txt files,
+  Word .docx tables, Toolbox and LIFT (FieldWorks) dictionaries, ELAN .eaf
+  files and, only when the person asks, USFM scripture: paired verse by verse
+  with the other language's text (`usfm_source`), held back from training
+  until its holders say so. `into` is `parallel`, `test` or `lexicon` (a word
+  list: the rails measure what looking words up scores). It reports counts
+  and columns, never sentences.
+- **`try_translation`** translates up to 10 of the person's sentences with
+  the model the project serves on this computer (loopback only). What a
+  model writes is never relayed when it learned from local-only sentences or
+  its training terms were never recorded: the sentences are not sent, and
+  the agent gets the model's own page for the person to open. When the server asks for an
+  access token, the person tries it on that page; a token is never handed to
+  an agent.
+- Full profile: `run_benchmark` takes method `lexicon` (the dictionary floor;
+  `model` is the dictionary file and is required, `attest_local_transport`
+  does not apply). `forge_status` in `serving` names
+  `npx champollion connect <model dir> --app <the app folder>` and says a
+  model trained on local-only sentences needs `--holders-agreed-by`, a forge
+  flag no tool ever passes: it is the holders' own answer, never an agent's.
+- Tests: a scripted person (no LLM) walks the rails profile from an empty
+  folder to an evaluated model, to a private-use language and to a real one
+  by name; the same walk records the site's demo and runs from the packages
+  as they would ship. A lockstep test holds the `champollion` dependency
+  floor to the CLI in this tree.
+
 ## 0.3.2 (2026-10-07)
 
 Requires champollion 0.5.3. The `translate` tool's default model is the

package/LICENSE

@@ -130,4 +130,4 @@ software under these terms.
 **Use** means anything you do with the software requiring one
 of your licenses.
 
-Required Notice: Copyright Curtis Forbes — Champollion (https://champollion.dev)
+Required Notice: Copyright Epistemic Toolworks™ (Game Day Suits Ltd.) — Champollion (https://champollion.dev)

package/README.md

@@ -2,15 +2,24 @@
 
 MCP (Model Context Protocol) server for Champollion. Lets an AI agent take a person from "we want machine translation for our language" to a measured, deployable model — find the language and what exists for it, keep the community's data private, baseline existing models (including ones on your own machine), train with guardrails, prove the result, and translate — plus browse and run the public benchmark queue.
 
-> **Champollion** is infrastructure for trustworthy machine-translation evaluation across every language — source-available and free for noncommercial use (the evaluation harness and shared registries are open source) — the test sets and the map that show who can translate what, how good each method is, and where the gaps are. Public benchmarks on open data rank every method (human and machine); sovereign benchmarks are secret community-owned test sets we never see. The infrastructure is source-available and singly stewarded; the test sets and the methods for a community's language belong to that community — designed to work with communities, never hosting their corpora. This server is the agent-facing door into that network ([champollion.dev/docs/network](https://champollion.dev/docs/network/)). This server itself is PolyForm Noncommercial 1.0.0 (see [LICENSE](LICENSE)): free for noncommercial use; using it for a commercial purpose is not covered by this license. Who is covered, in plain words with examples: [Who may use this](https://champollion.dev/docs/getting-started/who-may-use-this).
+> **Champollion — on rails, with guardrails.** Machine translation development and deployment on rails, built with low-resource and Indigenous language communities in mind. This server is the agent's door onto the rails: its default profile gives a small agent six tools that walk a project from an empty folder to a measured model on the person's own computer, telling the agent to ask the person every question only they can answer (the server cannot check that it did), and reporting counts and columns — never a sentence from a local-only file. The rails promise process, not quality. This server itself is PolyForm Noncommercial 1.0.0 (see [LICENSE](LICENSE)): source-available and free for noncommercial use; using it for a commercial purpose is not covered by this license. Who is covered, in plain words with examples: [Who may use this](https://champollion.dev/docs/getting-started/who-may-use-this).
 
 ## What it does
 
-When connected to an agent (Claude Code, Cursor, …), the server exposes tools, resources, and prompts built around one flow: **"let's build a model for our language — how do we start?"** — discover what exists → protect your own data → baseline → build → prove → deploy. (Contributing compute to the public benchmark is the second flow.)
+It has two profiles:
+
+- **rails** (the default) — six tools that walk one language project end to
+  end on the person's own computer, with instructions a small agent can hold
+  ([below](#the-rails-profile--the-default)).
+- **full** — every tool listed under [Tools](#tools), for the whole network
+  (atlas, benchmarks, forge, publishing): `npx champollion-mcp-server --profile full`
+  (or `CHAMPOLLION_MCP_PROFILE=full`).
+
+When connected to an agent (Claude Code, Cursor, …) with the full profile, the server exposes tools, resources, and prompts built around one flow: **"let's build a model for our language — how do we start?"** — discover what exists → protect your own data → baseline → build → prove → deploy. (Contributing compute to the public benchmark is the second flow.)
 
 ### Tools
 
-Arguments: `name` is required, `name?` is optional. Every tool that takes ONE language also accepts it as `language` — `code` / `language` means either name works (pass one). The original names keep working.
+These are the full profile's (`--profile full`). Arguments: `name` is required, `name?` is optional. Every tool that takes ONE language also accepts it as `language` — `code` / `language` means either name works (pass one). The original names keep working.
 
 #### Discover — what exists for a language
 
@@ -105,6 +114,28 @@ npm test          # run unit tests
 npm start         # start on stdio (for agent connection)
 ```
 
+### The rails profile — the default
+
+```bash
+npx champollion-mcp-server                     # the rails profile
+npx champollion-mcp-server --profile full      # every tool (or CHAMPOLLION_MCP_PROFILE=full)
+```
+
+Six tools and short instructions (`instructions-rails.md`, under 7,500
+characters) that walk one language project end to end on the person's own
+computer: `start_project`, `project_status` (THE next step, read from the
+project's files), `run_next_step`, `add_data` (spreadsheets, Word tables,
+.csv/.tsv, Toolbox and LIFT dictionaries, ELAN files, and USFM scripture on
+request — counts and columns reported, never sentences), `try_translation`
+(the served model on a few of the person's sentences — a model that learned
+from local-only sentences is never relayed to the agent; the person gets its
+page instead) and `explain`. The
+people decide: `run_next_step` refuses a step only a person can take, runs a
+step that asks the data's holders only with their answers, an install or
+training step only with `confirmed: true`, and only the command
+`project_status` just named. Every command is a bounded `champollion` or
+`nmt-forge` process.
+
 ## Connect to your agent
 
 ### Claude Code / Antigravity

package/bin/server.js

@@ -6,9 +6,11 @@
  * an AI agent's MCP client (Claude Code, Antigravity, Cursor, etc.)
  * or run directly for testing:
  *
- *   node bin/server.js
+ *   node bin/server.js                  # the rails profile (the default)
+ *   node bin/server.js --profile full   # every tool
  *
- * The server exposes read-only tools for discovering what exists for a
+ * The rails profile walks one language project end to end with six tools.
+ * The full profile exposes read-only tools for discovering what exists for a
  * language (cited cards, benchmarks, results, contests), plus action tools
  * that run benchmarks, drive nmt-forge training and translate — every one
  * that spends or publishes requires the user's explicit confirmation.
@@ -16,5 +18,9 @@
 
 import { createServer } from '../src/index.js';
 
-const server = await createServer();
+// --profile rails (the default): the six-tool rails profile (src/rails.js);
+// --profile full: every tool.
+const i = process.argv.indexOf('--profile');
+const profile = i >= 0 ? process.argv[i + 1] : undefined;
+const server = await createServer(profile ? { profile } : undefined);
 await server.start();

package/instructions-rails.md

@@ -0,0 +1,129 @@
+# Champollion — machine translation on rails
+
+You help people build a translation method for their language, on their own
+computer. The rails name every step; you walk them, and the people decide.
+
+## The loop
+
+1. No project yet → `start_project` (folder; `from` = the language they will
+   put in, `to` = the language they want out; a private-use code like `qaa`
+   needs its name). Pass each language exactly as the person named it — never
+   a name or code they did not say; a language they know no code for is `qaa`
+   with their name. No name for it yet? Ask what they want to call it for
+   now — their choice, never yours. Ask the person what the translations are for and pass it
+   as `purpose`. The first call makes nothing: say its `ask_first` to the
+   person, then make the call it gives for their answer.
+2. `project_status` → read `step.mode`, `step.say`, `step.why`. `step.call`
+   is the exact tool call that takes the step (`step.command` is what the
+   rails run — never a tool name); a `<…>` in it is a slot for the person's
+   answer or file, never to be sent as it is.
+3. Do what the mode says:
+   - **auto** — `run_next_step` with the `step_id`.
+   - **confirm** — tell the person what it does (installs, training), ask
+     yes/no; only on yes, `run_next_step` with `confirmed: true`. On "not
+     now", `run_next_step` with `declined: true`: nothing runs, and it is not
+     asked again this session. (When "not-now" is one of a question's own
+     answers, pass it in `answers` instead: it is recorded.)
+   - **ask_user** — ask the person `step.question` in plain words; pass their
+     answers, by the keys in `step.answers`, to `run_next_step`. Never answer
+     for them, never guess, never fill an answer from a file.
+   - **wait** — something is running. Make `step.call` (`project_status`,
+     waiting up to 2 minutes) and repeat it while the step stays `wait`. Only
+     if the tools said it takes hours, tell the person when to ask you again.
+   - **use_tool** — YOU do it now, with `step.tool` (e.g. `add_data` for the
+     files the person named), as `step.say` says. Do not hand it back.
+   - **human_only** — a person does it: tell them what `step.say` says.
+4. Back to 2. After any change you or the person made by hand, call
+   `project_status` again — the next step is always read from the files.
+5. No step left (`step: null`) → the rails are done: tell the person what
+   `finished` says (where to try the model, what they could do next).
+
+## Bringing in data
+
+`add_data` takes each file the person names WHERE IT IS — any path; never ask
+them to move or copy it (`inbox/` is only a place they may drop files). Call
+it with just the path first: it reads the layout itself (a header row naming
+the languages decides the columns) and asks only when it cannot tell — don't
+ask the person about columns or headers before trying. Use `into: "test"` for
+the sentences a fluent speaker checked — the test set no model ever learns
+from. If it asks which column is which language,
+ask the person; never decide from the content. A result with `also` names
+more in the same file (a dictionary's example sentences as pairs) and the
+exact `add_data` call that brings it in — make it unless the person's terms
+for that file rule it out. Every file the person named goes in: if
+`files_not_added` appears, bring each in (its refusal says how) or tell the
+person which is left out and why. Spreadsheets, Word tables,
+Toolbox and LIFT dictionaries and ELAN files all come in this way; a word
+list goes in with `into: "lexicon"` (the rails measure what looking words up
+scores). Scripture (USFM) comes in only if the person asks, with the other
+language's text as `usfm_source`, and no model learns from it until its
+holders say so.
+
+## Privacy — you are an outside service
+
+What you read goes to your model provider. Never open, print or summarize the
+person's data files, test sentences or dictionaries — use `add_data`, which
+reports counts and columns only. A file marked local-only stays on this
+computer, and the tools refuse anything that would send it away.
+
+## Trying the model
+
+Once the model is served, `try_translation` translates a few of the person's
+own sentences with it. A model that learned from local-only sentences can
+write them back, so for such a model you get only the address of its own page
+— send the person there, and do not ask them to paste its translations to you.
+
+## Making it better
+
+A served model is where rounds begin, not where the rails end. Each round: a
+wishlist sheet says what would help most, the people write sentences they want
+translated, the model drafts them onto a sheet,
+the speaker marks each draft right or wrong and fixes the wrong ones, and the
+model learns again. Forge judges each round on the dev sentences and keeps the
+model in use unless the new one is measurably better. The sheets hold their
+sentences: never open them; relay the counts the tools print.
+
+Each round ends with a report step (`champollion improve report`). Tell the
+people what it says: the progress first — each number with its unit and what
+it was measured on — then its checks and its next steps, as things they can do.
+Encourage them with what is real; never more than the numbers say.
+
+`waiting_for_agreement` lists files whose speakers have not agreed yet — the
+rails go on without them. Ask each one's question once a session, gently; only
+when the person says everyone agreed, make its call with their yes.
+
+## Honesty
+
+Pass on every caveat and warning the tools print, word for word. When you tell
+the person what has been done — trained, scored, served — say it from
+`true_now` in `project_status`, and never more than it says. The rails
+promise the person will KNOW how good a model is on their own test sentences —
+not that it is good. A small model trained on a few thousand pairs is usually a
+phrasebook for phrases like the ones it saw. A fluent speaker decides what is
+fit to use. Never call a score good or bad yourself; say what the tool said.
+Then say it in plain words: chrF++ is out of 100 (higher is closer to the
+speaker's own sentences); a range such as 14–22 is how sure the tools are, not
+two results; a model is "the first small model", not its folder name.
+
+Once a model is served, `project_status` carries `model_in_use` beside the
+improve rounds' steps: its try page, and `for_the_person` — the command that
+puts it into their app or website (`champollion connect`), which they run when
+they want it. Tell them both once; the rounds go on either way.
+
+## Money and installs
+
+Nothing installs, trains, spends or publishes without the person's yes (the
+confirm mode). If a step needs `uv` and it is missing, tell the person to
+install it from https://docs.astral.sh/uv/ — do not download installers.
+
+## When something refuses
+
+A refusal says what, why and the fix. Pass it on in plain words and follow
+the fix, or call `project_status`. A step that failed twice is not run again
+until the person decides: tell them what it said, then either they fix it
+(a corrected command in a terminal is fine) or they say to try again
+(`confirmed: true`). `explain` has short texts on the rails,
+privacy, quality, the modes, and stepping off the rails.
+
+If they want help from people: "Having trouble, or want us to help with the
+project? Let's talk" — https://champollion.dev. They never need us to finish.

package/instructions.md

@@ -10,7 +10,7 @@ for it.
 
 ## The flow this server is built for
 
-Someone says: "Let's build a Cree model for our school" or "an Atya phrasebook for the hospital — how do we start?" Walk them through six stages. Each stage has tools. The human-readable version of this flow, with the exact commands, is https://champollion.dev/docs/build-mt-for-your-language — share it with the user.
+Someone says: "Let's build a Cree model for our school" or "an Atya phrasebook for the hospital — how do we start?" Walk them through six stages. Each stage has tools. The human-readable version of this flow, with the exact commands, is https://champollion.dev/docs/agents/shell — share it with the user.
 
 | Stage | What it answers | Tools |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "champollion-mcp-server",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "MCP server for Champollion — takes an agent from \"we want MT for our language\" to a measured model: cited language cards, benchmarks, local and hosted baselines, guarded nmt-forge training, contests, and the public benchmark queue.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "bin",
     "src",
     "instructions.md",
+    "instructions-rails.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -27,7 +28,10 @@
     "machine-translation",
     "benchmarking",
     "low-resource-languages",
-    "language-cards"
+    "language-cards",
+    "indigenous-languages",
+    "nmt-training",
+    "agents"
   ],
   "author": "Curtis Forbes",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -39,7 +43,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "champollion": "^0.5.3",
+    "champollion": "^0.6.0",
     "zod": "^3.25 || ^4.0"
   },
   "repository": {

package/src/index.js

@@ -58,6 +58,7 @@ import { selectCorpora, formatCorpora, MAX_LIMIT as CORPORA_MAX_LIMIT } from './
 import { metricReliability, formatReliability, cardFamilyClaims } from './tools/reliability.js';
 import { translateTexts, formatTranslateResult, translateResultIsError, TRANSLATE_METHODS } from './tools/translate.js';
 import { trainingGuardrails, formatTrainingGuardrails } from './tools/training.js';
+import { registerRailsTools } from './rails.js';
 import {
   forgeTool, forgeToolsIn, FORGE_SCORING_TIMEOUT_MS, lintNextHint, lintSeverityCounts,
   compareSummary, compareNextHint, discoverCardCrossCheck, preflightNextHint,
@@ -81,18 +82,47 @@ async function loadInstructions(path) {
   }
 }
 
+/** The rails profile's server: registerRailsTools + instructions-rails.md. */
+async function createRailsServer(here) {
+  const instructions = await loadInstructions(resolve(here, '..', 'instructions-rails.md'));
+  const { version } = JSON.parse(await readFile(resolve(here, '..', 'package.json'), 'utf-8'));
+  const server = new McpServer({ name: 'champollion-rails', version },
+    instructions ? { instructions } : undefined);
+  registerRailsTools(server);
+  return {
+    async connect(transport) { await server.connect(transport); },
+    async start() {
+      await server.connect(new StdioServerTransport());
+      process.stderr.write('Champollion MCP server (rails profile) running on stdio\n');
+    },
+  };
+}
+
 /**
- * Create and configure the MCP server with all tool registrations.
+ * Create and configure the MCP server.
+ *
+ * The default profile is `rails` (founder, 2026-10-10): six tools and short
+ * instructions that walk a language project end to end. `full` — every
+ * tool (queue, atlas, benchmarks, forge, publishing) — is by request:
+ * `--profile full` or CHAMPOLLION_MCP_PROFILE=full.
  *
  * @returns {{ start: () => Promise<void> }}  Server object with a start method.
  */
-export async function createServer() {
+export async function createServer({ profile = process.env.CHAMPOLLION_MCP_PROFILE || 'rails' } = {}) {
   // Resolve paths relative to this file (for reading instructions.md,
   // CONTRIBUTING.md, etc.). Computed before server creation because the
   // server's `instructions` are loaded from disk at construction time.
   const __dirname = dirname(fileURLToPath(import.meta.url));
   const repoRoot = resolve(__dirname, '..', '..');
 
+  // The rails profile (2026-10-09; the default since 2026-10-10): six tools
+  // and short instructions a small agent can hold — the language-project
+  // journey, end to end. The full profile below is unchanged.
+  if (profile === 'rails') return createRailsServer(__dirname);
+  if (profile !== 'full') {
+    throw new Error(`unknown MCP profile "${profile}" (rails or full)`);
+  }
+
   // Load the agent behavioral guide and hand it to the SDK as the server's
   // `instructions`. The SDK surfaces these in the MCP `initialize` result so
   // connecting clients can show the model server-level guidance. Falls back to