altalandi-mcp 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Altalandi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Altalandi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,53 +1,71 @@
 # 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 (Claude Code, etc.) can
-call. stdio transport.
+[Altalandi](https://altalandi.is), native-Icelandic refinement with a
+meaning-preservation check, as a tool any MCP client can call. stdio transport.
 
-## Use it in Claude Code
+## Set up (Claude Code or Codex)
 
-Add to your MCP config (`.mcp.json` in the project, or your Claude Code config):
+Connect this computer once. This opens altalandi.is, you approve, and the key
+is stored locally. You never copy it:
 
-```json
-{
-  "mcpServers": {
-    "altalandi": {
-      "command": "npx",
-      "args": ["-y", "altalandi-mcp"],
-      "env": { "ALTALANDI_API_KEY": "rtv_..." }
-    }
-  }
-}
+```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
 ```
 
-Mint a key at <https://altalandi.is/portal>. Then ask Claude to use the
-**`refine_icelandic`** tool.
+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? })` → the native
-Icelandic text, a 0–100 nativeness score, and whether meaning was preserved.
+`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 —
+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` | — | your key (Bearer). Mint at https://altalandi.is/portal |
+| `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) |
 
-## Run standalone
+Each API request has a fixed 300-second deadline, including the response body,
+so a stalled provider cannot leave the tool hanging.
 
-```bash
-ALTALANDI_API_KEY=rtv_... npx -y altalandi-mcp     # speaks MCP over stdio
-```
+## 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. The hosted API is metered per key.
+MIT licensed. Requires Node ≥ 18.

package/api-client.mjs

@@ -0,0 +1,54 @@
+export const REFINE_TIMEOUT_MS = 300_000;
+
+/**
+ * Send one MCP refinement request under a single deadline. The timer remains
+ * active while the response body is consumed, since a server can send headers
+ * and then stall indefinitely.
+ *
+ * Timer/fetch injection is intentionally private test plumbing; production
+ * callers use the stable 300-second timeout and platform implementations.
+ */
+export async function requestRefine(
+  baseUrl,
+  apiKey,
+  body,
+  {
+    fetchImpl = globalThis.fetch,
+    setTimeoutImpl = globalThis.setTimeout,
+    clearTimeoutImpl = globalThis.clearTimeout,
+  } = {},
+) {
+  const controller = new AbortController();
+  const timeout = setTimeoutImpl(() => controller.abort(), REFINE_TIMEOUT_MS);
+
+  try {
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}/v1/refine`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`Altalandi request timed out after ${REFINE_TIMEOUT_MS} ms.`);
+      }
+      throw error;
+    }
+
+    try {
+      return { response, data: await response.json() };
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`Altalandi request timed out after ${REFINE_TIMEOUT_MS} ms.`);
+      }
+      return { response, data: {} };
+    }
+  } finally {
+    clearTimeoutImpl(timeout);
+  }
+}

package/format-response.mjs

@@ -0,0 +1,55 @@
+/**
+ * What actually happened to the caller's text. `meaningPreserved` alone cannot
+ * say: when the candidate veto refuses a broken rewrite, the meaning check has
+ * already passed, so `meaningPreserved` is still true while the ORIGINAL comes
+ * back. An agent reading "meaning preserved" would then report a rewrite that
+ * never shipped.
+ *
+ *   rewritten   the output is a verified rewrite
+ *   refused     a rewrite was produced and rejected; the original is returned
+ *   unchanged   the text needed no rewrite
+ *   unverified  meaning could not be established; do not present as verified
+ *
+ * Responses from older API versions have no `rewriteAttempted` or
+ * `rejectionReason`; they fall through to the meaningPreserved verdict, exactly
+ * as before.
+ */
+export function outcomeOf(data) {
+  if (data?.rejectionReason) return "refused";
+  if (data?.meaningPreserved === false) return "refused";
+  if (data?.rewriteAttempted === false) return "unchanged";
+  if (data?.meaningPreserved !== true) return "unverified";
+  return "rewritten";
+}
+
+export function formatRefineResponse(data) {
+  const quality = data?.quality || {};
+  const outcome = outcomeOf(data);
+  const lines = [
+    String(data?.output ?? ""),
+    "",
+    `— nativeness ${quality.nativenessScore ?? "n/a"}/100`,
+  ];
+
+  if (outcome === "refused") {
+    if (data?.meaningPreserved === false) {
+      lines.push("— ⚠ MEANING DRIFT — original returned unchanged");
+    } else {
+      lines.push("— ⚠ REWRITE REFUSED — the original is returned unchanged");
+    }
+    if (data?.rejectionReason) lines.push(`— reason: ${String(data.rejectionReason)}`);
+  } else if (outcome === "unchanged") {
+    lines.push("— no rewrite needed — the text is returned as it was");
+  } else if (outcome === "unverified") {
+    lines.push("— ⚠ MEANING UNVERIFIED — check did not run or could not complete; review before use");
+  } else {
+    lines.push("— meaning preserved");
+  }
+
+  const warnings = Array.isArray(data?.warnings) ? data.warnings : [];
+  if (warnings.length) {
+    lines.push("", "Warnings:", ...warnings.map((warning) => `- ${String(warning)}`));
+  }
+
+  return lines.join("\n");
+}

package/key.mjs

@@ -0,0 +1,30 @@
+// Where the MCP server finds its API key, in order:
+//   1. ALTALANDI_API_KEY (or ALTALANDI_KEY) in its environment;
+//   2. the key `npx altalandi login` stored on this computer.
+// The second makes the MCP server plug-and-play: after one login, adding it
+// to Claude Code or Codex needs no secret in any config file. The location
+// matches the CLI's (tools/cli/auth.mjs); ALTALANDI_CONFIG_DIR overrides it.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export function configDir({ env = process.env, home = homedir(), platform = process.platform } = {}) {
+  if (env.ALTALANDI_CONFIG_DIR) return env.ALTALANDI_CONFIG_DIR;
+  if (platform === "win32") return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "altalandi");
+  return path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "altalandi");
+}
+
+/** { key, source } where source is "env", "login" or "none". Never throws. */
+export function resolveKey(opts = {}) {
+  const env = opts.env ?? process.env;
+  const fromEnv = env.ALTALANDI_API_KEY || env.ALTALANDI_KEY;
+  if (fromEnv) return { key: fromEnv, source: "env" };
+  try {
+    const data = JSON.parse(readFileSync(path.join(configDir({ ...opts, env }), "credentials.json"), "utf8"));
+    if (data && typeof data.apiKey === "string" && data.apiKey) return { key: data.apiKey, source: "login" };
+  } catch {
+    /* no stored login */
+  }
+  return { key: "", source: "none" };
+}

package/package.json

@@ -1,18 +1,47 @@
 {
   "name": "altalandi-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server exposing Altalandi (native-Icelandic refinement) as a tool for Claude Code and any MCP client.",
   "type": "module",
-  "bin": { "altalandi-mcp": "./server.mjs" },
-  "files": ["server.mjs", "README.md", "LICENSE"],
+  "bin": {
+    "altalandi-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "key.mjs",
+    "api-client.mjs",
+    "format-response.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "keywords": [
-    "icelandic", "íslenska", "mcp", "model-context-protocol", "claude",
-    "claude-code", "altalandi", "nlp", "translation", "agent"
+    "icelandic",
+    "íslenska",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "codex",
+    "altalandi",
+    "nlp",
+    "translation",
+    "agent"
   ],
   "homepage": "https://altalandi.is",
-  "repository": { "type": "git", "url": "git+https://github.com/pbidhjorvar/ritvit.git", "directory": "tools/mcp" },
-  "bugs": { "url": "https://github.com/pbidhjorvar/ritvit/issues" },
-  "engines": { "node": ">=18" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pbidhjorvar/ritvit.git",
+    "directory": "tools/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/pbidhjorvar/ritvit/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.8"

package/server.mjs

@@ -2,50 +2,58 @@
 // Altalandi MCP server — exposes native-Icelandic refinement as a tool that
 // Claude Code (and any MCP client) can call. stdio transport.
 //
-//   ALTALANDI_API_KEY=... npx -y altalandi-mcp
-//
-// Claude Code config (.mcp.json or your Claude Code config) — no install:
-//   { "mcpServers": { "altalandi": {
-//       "command": "npx",
-//       "args": ["-y", "altalandi-mcp"],
-//       "env": { "ALTALANDI_API_KEY": "rtv_..." } } } }
+// The key comes from ALTALANDI_API_KEY or, failing that, from the login that
+// `npx altalandi login` stored on this computer, so no config file ever holds
+// a secret:
+//   claude mcp add altalandi -s user -- npx -y altalandi-mcp
+//   codex mcp add altalandi -- npx -y altalandi-mcp
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { requestRefine } from "./api-client.mjs";
+import { formatRefineResponse, outcomeOf } from "./format-response.mjs";
+import { resolveKey } from "./key.mjs";
 
 const BASE = (process.env.ALTALANDI_BASE_URL || "https://altalandi.is/api").replace(/\/$/, "");
-const KEY = process.env.ALTALANDI_API_KEY || process.env.ALTALANDI_KEY;
-
-const server = new McpServer({ name: "altalandi", version: "0.1.0" });
+const server = new McpServer({ name: "altalandi", version: "0.2.0" });
 
 server.tool(
   "refine_icelandic",
-  "Rewrite English or stiff/AI-translated Icelandic into native-sounding Icelandic, with a meaning-preservation check. Use whenever you need Icelandic that must read like a native wrote it (marketing copy, UI strings, prose). Returns the refined text, a 0-100 nativeness score, and whether meaning was preserved (on drift it returns the original unchanged).",
+  "Rewrite English or stiff/AI-translated Icelandic into native-sounding Icelandic, with a meaning-preservation check. Use whenever you need Icelandic that must read like a native wrote it (marketing copy, UI strings, prose). Returns the refined text, a 0-100 nativeness score, an explicit meaning verdict, and every API warning. Only 'meaning preserved' is verified; 'MEANING UNVERIFIED' requires review. On drift it returns the original unchanged.",
   {
     text: z.string().describe("Text to refine (English or Icelandic)."),
     domain: z.enum(["general", "marketing", "data-analysis", "childrens-fiction"]).optional()
       .describe("Tunes register/idiom. Default general."),
     register: z.enum(["formal", "neutral", "warm"]).optional().describe("Tone. Default neutral."),
+    sourceLang: z.enum(["auto", "en", "is"]).optional()
+      .describe("Source-language hint. Default auto."),
   },
-  async ({ text, domain, register }) => {
+  async ({ text, domain, register, sourceLang }) => {
+    // Resolved per call, so a login made after the server started is picked up.
+    const { key: KEY } = resolveKey();
     if (!KEY) {
-      return { content: [{ type: "text", text: "ALTALANDI_API_KEY is not set for the MCP server." }], isError: true };
+      return { content: [{ type: "text", text:
+        "No Altalandi key found. Run `npx altalandi login` once on this computer, or set ALTALANDI_API_KEY." }],
+        isError: true };
     }
     try {
-      const res = await fetch(`${BASE}/v1/refine`, {
-        method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${KEY}` },
-        body: JSON.stringify({ text, domain, register }),
+      const { response, data } = await requestRefine(BASE, KEY, {
+        text,
+        domain,
+        register,
+        sourceLang,
       });
-      const data = await res.json().catch(() => ({}));
-      if (!res.ok) {
-        return { content: [{ type: "text", text: `Altalandi error ${res.status}: ${data.detail || res.statusText}` }], isError: true };
+      if (!response.ok) {
+        return { content: [{ type: "text", text: `Altalandi error ${response.status}: ${data.detail || response.statusText}` }], isError: true };
       }
-      const q = data.quality || {};
-      const drift = data.meaningPreserved === false ? " (MEANING DRIFT — original returned unchanged)" : "";
       return {
-        content: [{ type: "text", text: `${data.output}\n\n— nativeness ${q.nativenessScore ?? "n/a"}/100${drift}` }],
+        content: [{ type: "text", text: formatRefineResponse(data) }],
+        // MCP callers should not treat a refused rewrite (drift, a lost
+        // invariant, or a candidate veto) or an unverified response as a
+        // successfully refined artifact. "No rewrite needed" is a success. The
+        // full result remains visible so an agent can explain it.
+        isError: ["refused", "unverified"].includes(outcomeOf(data)),
       };
     } catch (e) {
       return { content: [{ type: "text", text: `Request failed: ${e.message}` }], isError: true };