altalandi-mcp 0.1.0 → 0.1.1

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,77 @@
-# 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.
-
-## Use it in Claude Code
-
-Add to your MCP config (`.mcp.json` in the project, or your Claude Code config):
-
-```json
-{
-  "mcpServers": {
-    "altalandi": {
-      "command": "npx",
-      "args": ["-y", "altalandi-mcp"],
-      "env": { "ALTALANDI_API_KEY": "rtv_..." }
-    }
-  }
-}
-```
-
-Mint a key at <https://altalandi.is/portal>. Then ask Claude to use the
-**`refine_icelandic`** tool.
-
-## The tool
-
-`refine_icelandic({ text, domain?, register?, sourceLang? })` → the native
-Icelandic text, a 0–100 nativeness score, and whether meaning was preserved.
-
-- `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.
-
-## Config
-
-| env | default | purpose |
-|-----|---------|---------|
-| `ALTALANDI_API_KEY` | — | your key (Bearer). Mint at https://altalandi.is/portal |
-| `ALTALANDI_BASE_URL` | `https://altalandi.is/api` | API base (override for self-hosting) |
-
-## Run standalone
-
-```bash
-ALTALANDI_API_KEY=rtv_... npx -y altalandi-mcp     # speaks MCP over stdio
-```
-
-MIT licensed. Requires Node ≥ 18. The hosted API is metered per key.
+# 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.
+
+## Use it in Claude Code
+
+Mint a key at <https://altalandi.is/portal>, store it in your password manager,
+then load it without putting the plaintext in shell history:
+
+```bash
+read -rsp "Altalandi API key: " ALTALANDI_API_KEY; echo
+export ALTALANDI_API_KEY
+```
+
+PowerShell 7: `$env:ALTALANDI_API_KEY = Read-Host "Altalandi API key" -MaskInput`.
+
+Launch Claude Code from that shell, then add this secret-free MCP config
+(`.mcp.json` in the project, or your Claude Code config). The server inherits
+the variable from its parent process:
+
+```json
+{
+  "mcpServers": {
+    "altalandi": {
+      "command": "npx",
+      "args": ["-y", "altalandi-mcp"]
+    }
+  }
+}
+```
+
+For CI, services, or GUI-launched clients, inject the variable with the host's
+secret manager. Never commit the plaintext key in MCP JSON. Then ask Claude to
+use the **`refine_icelandic`** tool.
+
+## The tool
+
+`refine_icelandic({ text, domain?, register?, sourceLang? })` → 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 text result.
+
+## Config
+
+| env | default | purpose |
+|-----|---------|---------|
+| `ALTALANDI_API_KEY` | — | your key (Bearer). Mint at https://altalandi.is/portal |
+| `ALTALANDI_BASE_URL` | `https://altalandi.is/api` | API base (override for self-hosting) |
+
+Each API request has a fixed 300-second deadline, including response-body
+download, so a stalled provider cannot leave the MCP tool hanging forever.
+
+## Run standalone
+
+```bash
+npx -y altalandi-mcp     # inherits ALTALANDI_API_KEY; speaks MCP over stdio
+```
+
+MIT licensed. Requires Node ≥ 18. Portal keys share a daily account-level
+billable-word budget; operator-issued keys remain per-key. Text and glossary
+fields count; each
+whitespace-delimited token is at least one unit, and an unbroken token uses one
+unit per 20 characters, rounded up.

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,23 @@
+export function formatRefineResponse(data) {
+  const quality = data?.quality || {};
+  const lines = [
+    String(data?.output ?? ""),
+    "",
+    `— nativeness ${quality.nativenessScore ?? "n/a"}/100`,
+  ];
+
+  if (data?.meaningPreserved === true) {
+    lines.push("— meaning preserved");
+  } else if (data?.meaningPreserved === false) {
+    lines.push("— ⚠ MEANING DRIFT — original returned unchanged");
+  } else {
+    lines.push("— ⚠ MEANING UNVERIFIED — check did not run or could not complete; review before use");
+  }
+
+  const warnings = Array.isArray(data?.warnings) ? data.warnings : [];
+  if (warnings.length) {
+    lines.push("", "Warnings:", ...warnings.map((warning) => `- ${String(warning)}`));
+  }
+
+  return lines.join("\n");
+}

package/package.json

@@ -1,21 +1,48 @@
-{
-  "name": "altalandi-mcp",
-  "version": "0.1.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"],
-  "keywords": [
-    "icelandic", "íslenska", "mcp", "model-context-protocol", "claude",
-    "claude-code", "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" },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.23.8"
-  },
-  "license": "MIT"
-}
+{
+  "name": "altalandi-mcp",
+  "version": "0.1.1",
+  "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",
+    "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"
+  ],
+  "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"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "license": "MIT"
+}

package/server.mjs

@@ -1,56 +1,63 @@
-#!/usr/bin/env node
-// 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_..." } } } }
-
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-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" });
-
-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).",
-  {
-    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."),
-  },
-  async ({ text, domain, register }) => {
-    if (!KEY) {
-      return { content: [{ type: "text", text: "ALTALANDI_API_KEY is not set for the MCP server." }], 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 data = await res.json().catch(() => ({}));
-      if (!res.ok) {
-        return { content: [{ type: "text", text: `Altalandi error ${res.status}: ${data.detail || res.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}` }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Request failed: ${e.message}` }], isError: true };
-    }
-  },
-);
-
-await server.connect(new StdioServerTransport());
+#!/usr/bin/env node
+// Altalandi MCP server — exposes native-Icelandic refinement as a tool that
+// Claude Code (and any MCP client) can call. stdio transport.
+//
+// Load ALTALANDI_API_KEY through the parent environment or a secret manager,
+// then run: npx -y altalandi-mcp
+//
+// Claude Code config (.mcp.json or your Claude Code config) — no plaintext
+// secret required; the child process inherits ALTALANDI_API_KEY:
+//   { "mcpServers": { "altalandi": {
+//       "command": "npx",
+//       "args": ["-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 } from "./format-response.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.1" });
+
+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, 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, sourceLang }) => {
+    if (!KEY) {
+      return { content: [{ type: "text", text: "ALTALANDI_API_KEY is not set for the MCP server." }], isError: true };
+    }
+    try {
+      const { response, data } = await requestRefine(BASE, KEY, {
+        text,
+        domain,
+        register,
+        sourceLang,
+      });
+      if (!response.ok) {
+        return { content: [{ type: "text", text: `Altalandi error ${response.status}: ${data.detail || response.statusText}` }], isError: true };
+      }
+      return {
+        content: [{ type: "text", text: formatRefineResponse(data) }],
+        // MCP callers should not treat an original-on-drift or unverified
+        // response as a successfully refined artifact. The full result remains
+        // visible so an agent can explain/review it instead of losing context.
+        isError: data.meaningPreserved !== true,
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Request failed: ${e.message}` }], isError: true };
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());