altalandi-mcp 0.3.0 → 0.7.7

package/README.md

@@ -1,71 +1,112 @@
-# altalandi-mcp
-
-An [MCP](https://modelcontextprotocol.io) server that exposes
-[Altalandi](https://altalandi.is), native-Icelandic refinement with a
-meaning-preservation check, as a tool any MCP client can call. stdio transport.
-
-## Set up (Claude Code or Codex)
-
-Connect this computer once. This opens altalandi.is, you approve, and the key
-is stored locally. You never copy it:
-
-```bash
-npx altalandi login
-```
-
-Then add the server. No key goes into any config file; the server reads the
-one `altalandi login` stored:
-
-```bash
-claude mcp add altalandi -s user -- npx -y altalandi-mcp   # Claude Code
-codex mcp add altalandi -- npx -y altalandi-mcp            # Codex
-```
-
-Ask for Icelandic and mention Altalandi, e.g. *"Write this in proper Icelandic
-with Altalandi."* The agent calls the **`refine_icelandic`** tool.
-
-### Without `altalandi login` (CI, services, other clients)
-
-Set `ALTALANDI_API_KEY` in the server's environment, from your host's secret
-manager. It takes precedence over a stored login. Mint a key at
-<https://altalandi.is/portal>. Never commit a plaintext key in MCP JSON.
-
-```json
-{ "mcpServers": { "altalandi": { "command": "npx", "args": ["-y", "altalandi-mcp"] } } }
-```
-
-## The tool
-
-`refine_icelandic({ text, domain?, register?, sourceLang? })` returns the native
-Icelandic text, a 0–100 nativeness score, an explicit meaning verdict, and every
-warning returned by the API.
-
-- `domain`: `general` \| `marketing` \| `data-analysis` \| `childrens-fiction`
-- `register`: `formal` \| `neutral` \| `warm`
-- `sourceLang`: `auto` \| `en` \| `is`
-
-**Meaning guarantee:** on Icelandic input where the rewrite can't be verified to
-preserve meaning, the tool returns the **original unchanged** and flags it,
-never a silent change.
-
-Only **meaning preserved** is a verified result. **MEANING UNVERIFIED** means the
-check did not run or could not complete; review that output before use. API
-warnings are included under a clear `Warnings:` section in the tool's result.
-
-## Config
-
-| env | default | purpose |
-|-----|---------|---------|
-| `ALTALANDI_API_KEY` | (the key from `altalandi login`) | your key (Bearer) |
-| `ALTALANDI_CONFIG_DIR` | `%APPDATA%\altalandi` / `~/.config/altalandi` | where `altalandi login` stored it |
-| `ALTALANDI_BASE_URL` | `https://altalandi.is/api` | API base (override for self-hosting) |
-
-Each API request has a fixed 300-second deadline, including the response body,
-so a stalled provider cannot leave the tool hanging.
-
-## Cost
-
-Calls are paid from the account's prepaid credit in krónur (a new account
-starts with trial credit). See <https://altalandi.is/verd>.
-
-MIT licensed. Requires Node ≥ 18.
+# altalandi-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes
+[Altalandi](https://altalandi.is), native-Icelandic refinement with a
+meaning-preservation check, as a tool any MCP client can call. stdio transport.
+
+## Set up (Claude Code or Codex)
+
+Connect this computer once. This opens altalandi.is, you approve, and the key
+is stored locally. You never copy it:
+
+```bash
+npx altalandi login
+```
+
+Then add the server. No key goes into any config file; the server reads the
+one `altalandi login` stored:
+
+```bash
+claude mcp add altalandi -s user -- npx -y altalandi-mcp   # Claude Code
+codex mcp add altalandi -- npx -y altalandi-mcp            # Codex
+```
+
+Ask for Icelandic and mention Altalandi, e.g. *"Write this in proper Icelandic
+with Altalandi."* The agent calls the **`refine_icelandic`** tool.
+
+### Without `altalandi login` (CI, services, other clients)
+
+Set `ALTALANDI_API_KEY` in the server's environment, from your host's secret
+manager. It takes precedence over a stored login. Mint a key at
+<https://altalandi.is/portal>. Never commit a plaintext key in MCP JSON.
+
+```json
+{ "mcpServers": { "altalandi": { "command": "npx", "args": ["-y", "altalandi-mcp"] } } }
+```
+
+## The tool
+
+`refine_icelandic({ text, domain?, register?, sourceLang?, report? })` returns two
+parts. The first is one Markdown block: the verdict and nativeness score, the text
+before and after (Fyrir / Eftir), a numbered list of changes with their reasons,
+why a rewrite was refused if it was, and what the call cost with the balance and
+free units left (Kostnaður). The second is the full refined text to apply. The
+tool tells the agent to show the block to you as it is after every call, so you see
+what changed and what it cost in the terminal or the editor, not only on the website.
+
+- `domain`: `general` \| `marketing` \| `data-analysis` \| `childrens-fiction`
+- `register`: `formal` \| `neutral` \| `warm`
+- `sourceLang`: `auto` \| `en` \| `is`
+- `noStore`: `true` means Altalandi never keeps this text. Otherwise free use (the free
+  daily units) is kept, with personal data scrubbed, to improve the service; paid use only
+  with consent ([privacy](https://altalandi.is/personuvernd#textabanki)).
+- `report`: `true` also writes `./altalandi-reports/altalandi-<time>-<id>.md`
+  (input, output, every change with its reason and layer, warnings, verdict).
+  Default: on when `ALTALANDI_REPORT=1`. Reports contain the text, so they are opt-in.
+
+**Meaning guarantee:** on Icelandic input where the rewrite can't be verified to
+preserve meaning, the tool returns the **original unchanged** and flags it,
+never a silent change.
+
+## Proofreading
+
+`proofread_icelandic({ text, suggestions?, minPrecision?, noStore? })` fixes only
+proven errors in Icelandic you wrote (punctuation, word boundaries, a misspelt word
+one slip from the right one) and keeps your wording. Everything else comes back as
+numbered **suggestions**, each with its reason and, when known, how sure it is. The
+agent shows you each one and applies only those you accept.
+
+- `suggestions`: `offer` (default: you choose) \| `apply` (the kinds of suggestion
+  measured right at least `minPrecision` of the time are applied and listed; the rest
+  are offered) \| `off` (only the safe fixes).
+- `minPrecision`: 0.5 to 0.99, default 0.9. A suggestion with a digit, or one that
+  changes a name, is never applied unasked.
+
+Then `record_suggestion_decisions({ resultId, decisions })` tells Altalandi which
+suggestions you used or ignored (numbers only, no text, free). That is how the
+suggestions get better.
+
+Only **meaning preserved** is a verified result. **MEANING UNVERIFIED** means the
+check did not run or could not complete; review that output before use. API
+warnings are included under a clear `Warnings:` section in the tool's result.
+
+## The Altalandi card
+
+In hosts that render MCP Apps (Claude Desktop, claude.ai), results appear in an
+Altalandi card: the text with a copy button, whether the meaning check passed,
+each change with its reason, and for proofreading each suggestion with **Nota**
+and **Hunsa** buttons. The card records the decisions itself. Terminals (Claude
+Code, Codex) get the same text as before. The server offers the card as the
+resource `ui://altalandi/result-v1.html`; both tools return its data as
+`structuredContent`.
+
+## Config
+
+| env | default | purpose |
+|-----|---------|---------|
+| `ALTALANDI_API_KEY` | (the key from `altalandi login`) | your key (Bearer) |
+| `ALTALANDI_CONFIG_DIR` | `%APPDATA%\altalandi` / `~/.config/altalandi` | where `altalandi login` stored it |
+| `ALTALANDI_BASE_URL` | `https://altalandi.is/api` | API base (override for self-hosting) |
+| `ALTALANDI_REPORT` | — | `1` = write a report for every call |
+| `ALTALANDI_REPORT_DIR` | `./altalandi-reports` (the server's working folder) | where reports go |
+
+Each API request has a fixed 300-second deadline, including the response body,
+so a stalled provider cannot leave the tool hanging.
+
+## Cost
+
+Every account gets 2,000 free units a day on the standard writer (about 2,000
+words); past that, calls are paid from prepaid credit in krónur, and a new account
+also starts with 500 kr. of trial credit. See <https://altalandi.is/verd>.
+
+MIT licensed. Requires Node ≥ 18.

package/api-client.mjs

@@ -52,3 +52,34 @@ export async function requestRefine(
     clearTimeoutImpl(timeout);
   }
 }
+
+/** The account behind the key (balance, free units), or null. Best-effort:
+ *  it only fills the cost lines of the review block. */
+export async function requestMe(baseUrl, apiKey, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const response = await fetchImpl(`${baseUrl}/v1/me`, {
+      headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" },
+      signal: AbortSignal.timeout(15_000),
+    });
+    return response.ok ? await response.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Report what the person chose for each proofreading suggestion (free; no
+ *  model runs; no text is sent). Returns {ok, recorded, refused} or {ok: false, error}. */
+export async function requestSuggestionDecisions(baseUrl, apiKey, body, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const response = await fetchImpl(`${baseUrl}/v1/suggestions`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(15_000),
+    });
+    const data = await response.json().catch(() => ({}));
+    return response.ok ? data : { ok: false, error: data.detail || response.statusText };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}