nectr-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Genc Kastrati
+
+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

@@ -0,0 +1,87 @@
+# nectr-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [nectr](https://nectr.ch), the markdown library for your LLMs.
+
+It lets a model **search** your library, **read** any saved page as clean markdown, **save** new pages, and **list** your projects. You don't need to paste links into the chat.
+
+- **Search:** a model can't guess your permalinks, but it can call `search_library("pricing page")`.
+- **Private pages:** pages you haven't shared have no working public link, but your key can still read them.
+- **Saving:** "save these docs and keep them current" becomes one step, and nectr re-crawls them on your plan's schedule.
+- **Freshness:** every read says when the page was last fetched.
+
+## Setup
+
+1. In nectr, open **Settings → API keys** and create a key. It starts with `nct_`.
+2. Add the server to your MCP client's configuration. Most desktop and editor clients use an `mcpServers` block like this:
+
+```json
+{
+  "mcpServers": {
+    "nectr": {
+      "command": "npx",
+      "args": ["-y", "nectr-mcp"],
+      "env": {
+        "NECTR_API_KEY": "nct_your_key_here"
+      }
+    }
+  }
+}
+```
+
+3. Restart the client. The four tools below should appear.
+
+Node.js 20 or newer is required.
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `NECTR_API_KEY` | yes | — | Your `nct_` API key |
+| `NECTR_URL` | no | `https://nectr.ch` | The nectr site to talk to, for a self-hosted instance |
+
+## Tools
+
+| Tool | What it does | Writes? |
+|---|---|---|
+| `search_library(query?, limit?)` | Finds saved pages by title or URL. Returns ids, URLs, freshness and a two-sentence summary per page, but **not** the bodies. Leave out `query` to list the most recently refreshed pages. | no |
+| `get_page(id \| url, max_chars?)` | Returns the clean markdown of one page, with when it was last fetched. Long pages are cut off at 40,000 characters by default; ask for more with `max_chars`. | no |
+| `convert_url(url, project_id?, force_refresh?)` | Saves a web page, PDF or DOCX to your library, optionally filed under a project. Counts against your monthly conversion quota unless the page is already saved. | yes |
+| `list_projects()` | Lists your projects with page counts and each project's public `llms.txt` URL. | no |
+
+There is deliberately **no delete**. A model that could delete your library by misreading a request isn't worth the convenience.
+
+Search returns summaries rather than bodies so that looking around your library doesn't fill the model's context. It reads a full page only when it chooses to.
+
+## Limits and errors
+
+The server uses the same developer API as any other script, so your plan's limits apply unchanged. Errors are worded so a model knows whether to retry:
+
+| nectr says | The model is told |
+|---|---|
+| 401: the key is invalid or revoked | Don't retry; you need a new key |
+| 402: over the monthly quota | Don't retry until the quota resets |
+| 422: the page can't be read (for example, it's behind a login) | nectr's reason, as given |
+| 429: rate limited | How many seconds to wait |
+| 503: the converter is busy | Retry in a few seconds |
+
+## Security
+
+**Your API key is stored in plain text in your MCP client's config file.** That's normal for MCP servers, but anyone who can read that file can use the key.
+
+- Create a dedicated key for each client, so you can revoke one without breaking the others.
+- If a key leaks, delete it under **Settings → API keys** in nectr. It stops working immediately.
+- This server only ever reads and adds pages. **The key itself is broader:** it has the same access to the nectr API as your account, deletion included, so treat it like a password.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+NECTR_API_KEY=nct_... node dist/index.js   # speaks MCP over stdio
+```
+
+The tests run against a fake nectr API (`test/fake-api.ts`) and through a real MCP client over an in-memory transport (`test/server.test.ts`).
+
+## License
+
+MIT

package/dist/client.js

@@ -0,0 +1,149 @@
+/**
+ * A thin client over the public nectr API (`/api/v1`), authenticated with an
+ * `nct_` API key. Every endpoint used here is the same one the developer API
+ * documents; this package adds no new server-side surface.
+ */
+/** An HTTP error from nectr, carrying what a caller needs to explain it. */
+export class NectrApiError extends Error {
+    status;
+    detail;
+    retryAfterSeconds;
+    constructor(status, detail, retryAfterSeconds = null) {
+        super(`nectr API ${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "NectrApiError";
+    }
+}
+/** nectr could not be reached at all (DNS, TLS, connection refused, timeout). */
+export class NectrUnreachableError extends Error {
+    siteUrl;
+    constructor(siteUrl, cause) {
+        super(`Could not reach nectr at ${siteUrl}`, { cause });
+        this.siteUrl = siteUrl;
+        this.name = "NectrUnreachableError";
+    }
+}
+const USER_AGENT = "nectr-mcp/0.1.0";
+const TIMEOUT_MS = 60_000; // a real crawl can take a while; reads are fast
+export class NectrClient {
+    apiKey;
+    siteUrl;
+    fetchImpl;
+    api;
+    constructor(apiKey, siteUrl, fetchImpl = fetch) {
+        this.apiKey = apiKey;
+        this.siteUrl = siteUrl;
+        this.fetchImpl = fetchImpl;
+        this.api = `${siteUrl}/api/v1`;
+    }
+    search(query, limit) {
+        const params = new URLSearchParams({ page: "1", limit: String(limit) });
+        if (query)
+            params.set("search", query);
+        return this.request("GET", `/conversions?${params}`);
+    }
+    getPage(id) {
+        return this.request("GET", `/conversions/${encodeURIComponent(id)}`);
+    }
+    convert(url, forceRefresh) {
+        return this.request("POST", "/conversions", { url, force_refresh: forceRefresh });
+    }
+    assignProject(id, projectId) {
+        return this.request("PATCH", `/conversions/${encodeURIComponent(id)}/project`, {
+            project_id: projectId,
+        });
+    }
+    listProjects() {
+        return this.request("GET", "/projects");
+    }
+    me() {
+        return this.request("GET", "/auth/me");
+    }
+    async request(method, path, body) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.api}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                    "User-Agent": USER_AGENT,
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            throw new NectrUnreachableError(this.siteUrl, err);
+        }
+        if (!res.ok) {
+            throw new NectrApiError(res.status, await readDetail(res), parseRetryAfter(res));
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+}
+/** FastAPI puts the message in `detail`: a string, or a list of validation errors. */
+async function readDetail(res) {
+    try {
+        const body = (await res.json());
+        if (typeof body.detail === "string")
+            return body.detail;
+        if (Array.isArray(body.detail)) {
+            return body.detail
+                .map((e) => (e && typeof e === "object" && "msg" in e ? String(e.msg) : String(e)))
+                .join("; ");
+        }
+    }
+    catch {
+        // Not JSON (a proxy error page, say) — fall through to the status text.
+    }
+    return res.statusText || `HTTP ${res.status}`;
+}
+function parseRetryAfter(res) {
+    const raw = res.headers.get("retry-after");
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+/**
+ * Turn a failure into a sentence a model can act on.
+ *
+ * The distinction that matters is retry-or-not: a model that sees an opaque
+ * failure retries it, and retrying a quota error or a revoked key only burns
+ * the caller's rate limit.
+ */
+export function describeError(err) {
+    if (err instanceof NectrUnreachableError) {
+        return `Could not reach nectr at ${err.siteUrl}. Check the network or NECTR_URL; retrying immediately is unlikely to help.`;
+    }
+    if (!(err instanceof NectrApiError)) {
+        return `Unexpected error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const wait = err.retryAfterSeconds;
+    switch (err.status) {
+        case 401:
+            return "The nectr API key was rejected — it is invalid or has been revoked. Do not retry; the user needs to create a new key in nectr under Settings → API keys.";
+        case 402:
+            return `Over the nectr plan's quota: ${err.detail} Do not retry until the quota resets or the plan is upgraded.`;
+        case 403:
+            return `nectr refused this request: ${err.detail}`;
+        case 404:
+            return "Not found in this nectr library. It may have been deleted, or the id is wrong.";
+        case 422:
+            return `nectr could not convert this page: ${err.detail}`;
+        case 429:
+            return `Rate limited by nectr. Wait ${wait ?? 60} seconds before trying again.`;
+        case 503:
+            return `nectr is busy converting other pages. Retry in ${wait ?? 5} seconds.`;
+        default:
+            return err.status >= 500
+                ? `nectr had a server error (${err.status}). Try again later.`
+                : `nectr returned ${err.status}: ${err.detail}`;
+    }
+}

package/dist/config.js

@@ -0,0 +1,20 @@
+export const DEFAULT_SITE_URL = "https://nectr.ch";
+/**
+ * Read configuration from the environment.
+ *
+ * Throws with a message meant for a person reading the MCP client's log: a
+ * server that starts without a key would fail every single tool call instead,
+ * and the model would be the one left guessing why.
+ */
+export function loadConfig(env = process.env) {
+    const apiKey = env.NECTR_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("NECTR_API_KEY is not set. Create a key in nectr under Settings → API keys " +
+            "and add it to this server's env in your MCP client configuration.");
+    }
+    if (!apiKey.startsWith("nct_")) {
+        throw new Error("NECTR_API_KEY does not look like a nectr API key (they start with nct_).");
+    }
+    const siteUrl = (env.NECTR_URL?.trim() || DEFAULT_SITE_URL).replace(/\/+$/, "");
+    return { apiKey, siteUrl };
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { NectrClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+let config;
+try {
+    config = loadConfig();
+}
+catch (err) {
+    // stdout is the MCP channel; anything meant for a person goes to stderr.
+    console.error(`nectr-mcp: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}
+const server = createServer(new NectrClient(config.apiKey, config.siteUrl));
+await server.connect(new StdioServerTransport());

package/dist/server.js

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+export const VERSION = "0.1.0";
+export function createServer(client) {
+    const server = new McpServer({ name: "nectr", version: VERSION });
+    registerTools(server, client);
+    return server;
+}

package/dist/tools.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { describeError } from "./client.js";
+/** Default cap on a page body returned to a model: roughly 10k tokens. */
+export const DEFAULT_MAX_CHARS = 40_000;
+const SEARCH_MAX = 25;
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const failure = (err) => ({
+    content: [{ type: "text", text: describeError(err) }],
+    isError: true,
+});
+function titleOf(p) {
+    return p.custom_title || p.title || p.url;
+}
+function statusNote(status) {
+    if (status === "completed")
+        return "";
+    if (status === "unreadable")
+        return " · UNREADABLE (login wall or placeholder; no content)";
+    return ` · ${status.toUpperCase()} (no content)`;
+}
+/** Compare URLs the way a person would: scheme/host case, fragment and trailing slash ignored. */
+export function sameUrl(a, b) {
+    const norm = (u) => {
+        try {
+            const p = new URL(u.trim());
+            p.hash = "";
+            return `${p.protocol}//${p.host}${p.pathname.replace(/\/+$/, "")}${p.search}`.toLowerCase();
+        }
+        catch {
+            return u.trim().replace(/\/+$/, "").toLowerCase();
+        }
+    };
+    return norm(a) === norm(b);
+}
+// ── Handlers (exported for tests) ───────────────────────────────────────────
+export async function searchLibrary(client, args) {
+    const query = args.query?.trim() || undefined;
+    const limit = Math.min(Math.max(args.limit ?? 10, 1), SEARCH_MAX);
+    try {
+        const list = await client.search(query, limit);
+        if (list.items.length === 0) {
+            return text(query
+                ? `No saved pages match "${query}". Use convert_url to add one.`
+                : "The library is empty. Use convert_url to add a page.");
+        }
+        const heading = query
+            ? `${list.items.length} of ${plural(list.total, "saved page")} matching "${query}":`
+            : `${list.items.length} most recently refreshed of ${plural(list.total, "saved page")}:`;
+        // Summaries and ids only. Bodies are fetched deliberately with get_page:
+        // returning ten full pages here would flood the context on every search.
+        const rows = list.items.map((p, i) => [
+            `${i + 1}. ${titleOf(p)}`,
+            `   id: ${p.id}`,
+            `   url: ${p.url}`,
+            `   fetched: ${p.fetched_at} · ${plural(p.word_count, "word")}${statusNote(p.status)}`,
+            ...(p.summary ? [`   summary: ${p.summary}`] : []),
+        ].join("\n"));
+        return text(`${heading}\n\n${rows.join("\n\n")}\n\nRead one with get_page(id).`);
+    }
+    catch (err) {
+        return failure(err);
+    }
+}
+export async function getPage(client, args) {
+    const maxChars = Math.max(args.max_chars ?? DEFAULT_MAX_CHARS, 1_000);
+    try {
+        let id = args.id?.trim();
+        if (!id) {
+            const url = args.url?.trim();
+            if (!url)
+                return failure(new Error("Pass either id or url."));
+            // By id rather than by public link: a private page has no working
+            // public link, but its owner's key can still read it by id.
+            const term = url.replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+            const list = await client.search(term, SEARCH_MAX);
+            const hit = list.items.find((p) => sameUrl(p.url, url));
+            if (!hit) {
+                return text(`No saved page for ${url}. Save it first with convert_url.`);
+            }
+            id = hit.id;
+        }
+        const page = await client.getPage(id);
+        if (page.status !== "completed") {
+            return text(`"${titleOf(page)}" (${page.url}) has no readable content${statusNote(page.status)}.`);
+        }
+        const body = page.markdown_content;
+        const meta = `id: ${page.id} · url: ${page.url} · fetched: ${page.fetched_at} · ${page.word_count} words`;
+        if (body.length <= maxChars)
+            return text(`${meta}\n\n${body}`);
+        return text(`${meta}\n\n${body.slice(0, maxChars)}\n\n[Truncated: showing ${maxChars} of ${body.length} characters. ` +
+            `Call get_page again with a larger max_chars for the rest.]`);
+    }
+    catch (err) {
+        return failure(err);
+    }
+}
+export async function convertUrl(client, args) {
+    try {
+        const saved = await client.convert(args.url, args.force_refresh ?? false);
+        let projectLine = "";
+        if (args.project_id) {
+            try {
+                await client.assignProject(saved.id, args.project_id);
+                projectLine = `\nAdded to project ${args.project_id}.`;
+            }
+            catch (err) {
+                // The page IS saved; say so rather than reporting the whole call as failed.
+                projectLine = `\nSaved, but could not add it to project ${args.project_id}: ${describeError(err)}`;
+            }
+        }
+        const how = saved.cached ? "Already in the library (served the saved copy)" : "Saved";
+        return text(`${how}: ${titleOf(saved)}\n` +
+            `id: ${saved.id} · ${saved.word_count} words · fetched: ${saved.fetched_at}` +
+            (saved.summary ? `\nsummary: ${saved.summary}` : "") +
+            projectLine +
+            `\n\nnectr keeps this page current on the plan's refresh schedule. Read it with get_page("${saved.id}").`);
+    }
+    catch (err) {
+        return failure(err);
+    }
+}
+export async function listProjects(client) {
+    try {
+        const [projects, me] = await Promise.all([client.listProjects(), client.me()]);
+        if (projects.length === 0)
+            return text("No projects yet. Projects are created in the nectr dashboard.");
+        const rows = projects.map((p) => `- ${p.name} (${plural(p.conversion_count, "page")})\n` +
+            `  id: ${p.id}\n` +
+            `  llms.txt: ${client.siteUrl}/p/${me.link_hash}/${p.slug}/llms.txt`);
+        return text(`${plural(projects.length, "project")}:\n\n${rows.join("\n")}\n\n` +
+            "Each llms.txt is public and lists only the project's shareable pages.");
+    }
+    catch (err) {
+        return failure(err);
+    }
+}
+// ── Registration ────────────────────────────────────────────────────────────
+export function registerTools(server, client) {
+    server.registerTool("search_library", {
+        title: "Search the nectr library",
+        description: "Search the user's saved nectr pages by title or URL. Returns ids, URLs, freshness and a " +
+            "short summary per page, not the page bodies. Omit query to list the most recently refreshed pages.",
+        inputSchema: {
+            query: z.string().max(500).optional().describe("Words from the title or URL. Omit to list recent pages."),
+            limit: z.number().int().min(1).max(SEARCH_MAX).optional().describe("Max results (default 10)."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, (args) => searchLibrary(client, args));
+    server.registerTool("get_page", {
+        title: "Read a saved page",
+        description: "Get the clean markdown of one saved nectr page, by id (from search_library) or by its " +
+            "original URL. Includes when it was last fetched. Works for private pages too.",
+        inputSchema: {
+            id: z.string().optional().describe("Page id from search_library or convert_url."),
+            url: z.string().optional().describe("The page's original URL, if the id is not known."),
+            max_chars: z
+                .number()
+                .int()
+                .min(1000)
+                .optional()
+                .describe(`Truncate the body after this many characters (default ${DEFAULT_MAX_CHARS}).`),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, (args) => getPage(client, args));
+    server.registerTool("convert_url", {
+        title: "Save a page to nectr",
+        description: "Convert a web page, PDF or DOCX to clean markdown and save it to the user's nectr library, " +
+            "where it is re-crawled automatically to stay current. Returns the new page's id and summary. " +
+            "Counts against the user's monthly conversion quota unless the page is already saved.",
+        inputSchema: {
+            url: z.url().describe("The http(s) URL to save."),
+            project_id: z.string().optional().describe("Optional project id (from list_projects) to file it under."),
+            force_refresh: z
+                .boolean()
+                .optional()
+                .describe("Re-crawl now even if the page is already saved (counts against the quota)."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, (args) => convertUrl(client, args));
+    server.registerTool("list_projects", {
+        title: "List nectr projects",
+        description: "List the user's nectr projects with their page counts and public llms.txt URLs.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, () => listProjects(client));
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "nectr-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for nectr: search, read and add to your nectr markdown library from any MCP client.",
+  "type": "module",
+  "bin": {
+    "nectr-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nectr",
+    "markdown",
+    "llm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/genckastrati/nectr-mcp.git"
+  },
+  "homepage": "https://github.com/genckastrati/nectr-mcp#readme",
+  "bugs": "https://github.com/genckastrati/nectr-mcp/issues",
+  "license": "MIT"
+}