nectr-mcp 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+It lets a model **search** your library, **read** any saved page as clean markdown, and **save** new pages. 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.
@@ -43,8 +43,7 @@ Node.js 20 or newer is required.
 |---|---|---|
 | `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 |
+| `convert_url(url, force_refresh?)` | Saves a web page, PDF or DOCX to your library. Counts against your monthly conversion quota unless the page is already saved. | yes |
 
 There is deliberately **no delete**. A model that could delete your library by misreading a request isn't worth the convenience.
 
@@ -72,8 +71,10 @@ The server uses the same developer API as any other script, so your plan's limit
 
 ## Development
 
+Running the server needs Node 20+, but **developing needs Node 22.12 or newer** (Vitest and the MCP Inspector require it). CI uses Node 24.
+
 ```bash
-npm install
+npm ci                 # not `npm install`: installs exactly the lockfile and never rewrites it
 npm run typecheck
 npm test
 npm run build
@@ -82,6 +83,37 @@ 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`).
 
+If `npm test` fails with **"Cannot find native binding"**, the `node_modules` folder was installed on another platform, for example inside a Linux container. `npm install` on top of it won't fix it. Delete `node_modules` and run `npm ci` again.
+
+### Trying it by hand with the MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) calls the tools directly, without a model, and shows exactly what a model would receive. Build first (`npm run build`), then use its CLI mode. **Put the server command before the options.** With the options first, the Inspector reports "No servers found in config file".
+
+```powershell
+# PowerShell; in bash, use $NECTR_API_KEY instead of $k
+$k = "nct_your_key"
+
+npx @modelcontextprotocol/inspector --cli node dist/index.js -e NECTR_API_KEY=$k --method tools/list
+npx @modelcontextprotocol/inspector --cli node dist/index.js -e NECTR_API_KEY=$k --method tools/call --tool-name search_library
+npx @modelcontextprotocol/inspector --cli node dist/index.js -e NECTR_API_KEY=$k --method tools/call --tool-name search_library --tool-arg query=pricing
+npx @modelcontextprotocol/inspector --cli node dist/index.js -e NECTR_API_KEY=$k --method tools/call --tool-name get_page --tool-arg id=PAGE-ID
+```
+
+Add `-e NECTR_URL=http://localhost:8000` to test against a local nectr backend. Leave out `--cli` for the web interface; the argument order is the same.
+
+The Inspector's own dependencies need a newer Node than this server does. If it fails with **"Cannot find native binding"** after you upgrade Node, delete its cached copy from the npx cache (`%LocalAppData%\npm-cache\_npx` on Windows, `~/.npm/_npx` elsewhere) and run it again.
+
+The quickest sanity check needs no key at all: `npx -y nectr-mcp` should print "NECTR_API_KEY is not set" and exit.
+
+### Publishing
+
+```bash
+npm version patch      # or minor / major; also bump VERSION in src/server.ts and USER_AGENT in src/client.ts
+npm publish            # prepublishOnly runs typecheck, tests and build first
+```
+
+npm refuses to publish from an account without two-factor authentication (error `E403`). Enable it under your npm account settings; `npm publish` then asks you to confirm in the browser or with `--otp=<code>`.
+
 ## License
 
 MIT

package/dist/client.js

@@ -25,7 +25,7 @@ export class NectrUnreachableError extends Error {
         this.name = "NectrUnreachableError";
     }
 }
-const USER_AGENT = "nectr-mcp/0.1.0";
+const USER_AGENT = "nectr-mcp/0.2.0";
 const TIMEOUT_MS = 60_000; // a real crawl can take a while; reads are fast
 export class NectrClient {
     apiKey;
@@ -50,14 +50,6 @@ export class NectrClient {
     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");
     }

package/dist/server.js

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

package/dist/tools.js

@@ -98,43 +98,16 @@ export async function getPage(client, args) {
 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", {
@@ -170,7 +143,6 @@ export function registerTools(server, client) {
             "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()
@@ -178,10 +150,4 @@ export function registerTools(server, client) {
         },
         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

@@ -1,6 +1,6 @@
 {
   "name": "nectr-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for nectr: search, read and add to your nectr markdown library from any MCP client.",
   "type": "module",
   "bin": {