notex-companion 0.3.0 → 0.3.2

package/README.md

@@ -2,8 +2,7 @@
 
 A local retrieval companion for [Notex](https://github.com/bhirmbani/notex). It reads a checkout's
 `graphify-out/graph.json` and serves deterministic search/query/path/node lookups over it — to the
-Notex browser page over loopback HTTP, and (once [TBR-69](https://linear.app/bmbn/issue/TBR-69)
-lands) to an MCP host over stdio.
+Notex browser page over loopback HTTP, and to an MCP host over stdio.
 
 ## What it reads
 
@@ -42,10 +41,15 @@ of starting a broken server.
 
 ```bash
 notex-companion [serve] [options]   # start the loopback HTTP server — the default command
-notex-companion mcp                 # start the stdio MCP server (stub until TBR-69 — the bin
-                                     # wiring ships here, the tool surface does not yet)
+notex-companion mcp                 # start the stdio MCP server — graph_status, graph_search,
+                                     # graph_query, graph_path, graph_node, plus notex_list_questions,
+                                     # notex_get_question, notex_get_answer, notex_save_answer
+                                     # (require .notex/notex.json — see docs/specs/notex-mcp-server.md)
 ```
 
+Setup, how it picks which checkout to serve, and a manual verification walkthrough:
+[`docs/testing/mcp-server-setup.md`](https://github.com/bhirmbani/notex/blob/main/docs/testing/mcp-server-setup.md).
+
 ### `serve` options
 
 | Flag | Default | Meaning |
@@ -63,7 +67,7 @@ browser's `localStorage`, keyed by Repository, and it is never sent to the Notex
 
 ## `apiVersion`
 
-`ping` and every op response report `apiVersion` (currently `0.1.0`). Compatibility rule — see
+`ping` and every op response report `apiVersion` (currently `0.2.1`). Compatibility rule — see
 [`companion-api.md` §1.1](https://github.com/bhirmbani/notex/blob/main/docs/specs/companion-api.md#11-apiversion-compatibility-rule-decided-by-tbr-66)
 for the full rationale:
 

package/dist/cli.js

@@ -6580,7 +6580,9 @@ var ERROR_CODES = {
   notFound: "not_found",
   graphUnreadable: "graph_unreadable",
   invalidRequest: "invalid_request",
-  graphLoading: "graph_loading"
+  graphLoading: "graph_loading",
+  forbidden: "forbidden",
+  notexApiError: "notex_api_error"
 };
 
 class OpError extends Error {
@@ -7012,7 +7014,9 @@ var ERROR_STATUS = {
   [ERROR_CODES.notFound]: 404,
   [ERROR_CODES.graphUnreadable]: 409,
   [ERROR_CODES.invalidRequest]: 422,
-  [ERROR_CODES.graphLoading]: 503
+  [ERROR_CODES.graphLoading]: 503,
+  [ERROR_CODES.forbidden]: 403,
+  [ERROR_CODES.notexApiError]: 502
 };
 function createHandler(opts) {
   return async (req) => {
@@ -7188,10 +7192,10 @@ function startNodeServer(opts) {
     }
   };
 }
-async function handleRequest(req, res, fetch) {
+async function handleRequest(req, res, fetch2) {
   try {
     const request = await toWebRequest(req);
-    const response = await fetch(request);
+    const response = await fetch2(request);
     res.statusCode = response.status;
     response.headers.forEach((value, key) => res.setHeader(key, value));
     res.end(Buffer.from(await response.arrayBuffer()));
@@ -33794,34 +33798,107 @@ function createGraphTools(ctx) {
   };
 }
 var LINK_MESSAGE = "Not linked to a Notex Repository — run `npx notex-companion link`";
-function notexStubHandler(ctx, notImplementedText) {
-  return () => {
-    const state = ctx.getConfigState();
-    if (state.kind === "unlinked")
-      return { isError: true, content: [{ type: "text", text: LINK_MESSAGE }] };
-    return { isError: true, content: [{ type: "text", text: notImplementedText }] };
-  };
-}
-function createNotexToolStubs(ctx) {
-  const notImplemented = (name) => `${name} is linked but not yet implemented — see TBR-72`;
+var MAX_INLINE_ANSWER_BYTES = 4096;
+function requireLinked(ctx) {
+  const state = ctx.getConfigState();
+  if (state.kind === "unlinked")
+    return { ok: false, error: { isError: true, content: [{ type: "text", text: LINK_MESSAGE }] } };
+  return { ok: true, config: state.config };
+}
+function fromNotexError(err) {
+  if (err instanceof OpError)
+    return errorResult(err);
+  throw err;
+}
+function truncateUtf8(text, maxBytes) {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= maxBytes)
+    return text;
+  let end = maxBytes;
+  while (end > 0 && (buf[end - 1] & 192) === 128)
+    end--;
+  if (end > 0) {
+    const lead = buf[end - 1];
+    const seqLen = lead >= 240 ? 4 : lead >= 224 ? 3 : lead >= 192 ? 2 : 1;
+    if (end - 1 + seqLen > maxBytes)
+      end--;
+  }
+  return buf.subarray(0, end).toString("utf8");
+}
+function summarizeAnswer(file2) {
+  if (file2.contentType === "upload")
+    return { id: file2.id, name: file2.name, contentType: "upload", createdAt: file2.createdAt };
+  const bytes = Buffer.byteLength(file2.content, "utf8");
+  if (bytes <= MAX_INLINE_ANSWER_BYTES) {
+    return { id: file2.id, name: file2.name, contentType: "text", content: file2.content, createdAt: file2.createdAt };
+  }
+  return { id: file2.id, name: file2.name, contentType: "text", content: truncateUtf8(file2.content, MAX_INLINE_ANSWER_BYTES), truncated: true, createdAt: file2.createdAt };
+}
+function createNotexTools(ctx) {
   return {
     notex_list_questions: {
       description: "List the bound Repository's Questions.",
       inputSchema: {},
-      handler: notexStubHandler(ctx, notImplemented("notex_list_questions"))
+      handler: async () => {
+        const linked = requireLinked(ctx);
+        if (!linked.ok)
+          return linked.error;
+        try {
+          const client = ctx.getNotexClient(linked.config);
+          const questions = await client.listContexts(linked.config.organizationId, linked.config.repositoryId);
+          const text = questions.length === 0 ? "No Questions yet." : questions.map((q) => `${q.id} — ${q.question}`).join(`
+`);
+          return { content: [{ type: "text", text }], structuredContent: { questions } };
+        } catch (err) {
+          return fromNotexError(err);
+        }
+      }
     },
     notex_get_question: {
       description: "A Question plus its Answers.",
       inputSchema: { questionId: exports_external.string().min(1) },
-      handler: notexStubHandler(ctx, notImplemented("notex_get_question"))
+      handler: async (args) => {
+        const linked = requireLinked(ctx);
+        if (!linked.ok)
+          return linked.error;
+        const { questionId } = args;
+        try {
+          const client = ctx.getNotexClient(linked.config);
+          const question = await client.getContext(linked.config.organizationId, questionId);
+          if (question.repositoryId !== linked.config.repositoryId) {
+            return errorResult(new OpError("not_found", `Unknown Question id: ${questionId}`));
+          }
+          const files = await client.listFiles(linked.config.organizationId, questionId);
+          const answers = files.map(summarizeAnswer);
+          const text = `${question.question}
+
+${answers.length} answer(s)`;
+          return { content: [{ type: "text", text }], structuredContent: { question, answers } };
+        } catch (err) {
+          return fromNotexError(err);
+        }
+      }
     },
     notex_get_answer: {
       description: "Full Answer content.",
       inputSchema: { answerId: exports_external.string().min(1) },
-      handler: notexStubHandler(ctx, notImplemented("notex_get_answer"))
+      handler: async (args) => {
+        const linked = requireLinked(ctx);
+        if (!linked.ok)
+          return linked.error;
+        const { answerId } = args;
+        try {
+          const client = ctx.getNotexClient(linked.config);
+          const answer = await client.getFile(linked.config.organizationId, answerId);
+          const text = answer.contentType === "upload" ? `${answer.name} (upload, no readable content)` : answer.content;
+          return { content: [{ type: "text", text }], structuredContent: { answer } };
+        } catch (err) {
+          return fromNotexError(err);
+        }
+      }
     },
     notex_save_answer: {
-      description: "Save a graph-drafted Answer. Strictly additive — always creates a new Answer, never updates or deletes. Exactly one of question/questionId.",
+      description: 'Save a graph-drafted Answer. Strictly additive — always creates a new Answer, never updates or deletes. Exactly one of question/questionId. `name` is the Answer\'s title, shown alongside the question in the Notex UI — write a short distinct label (e.g. "Auth flow overview"), not a restatement of the question text. `content` is the drafted prose itself, without the footer.',
       inputSchema: {
         question: exports_external.string().min(1).optional(),
         questionId: exports_external.string().min(1).optional(),
@@ -33829,11 +33906,111 @@ function createNotexToolStubs(ctx) {
         content: exports_external.string().min(1),
         sourceNodeIds: exports_external.array(exports_external.string()).min(1)
       },
-      handler: notexStubHandler(ctx, notImplemented("notex_save_answer"))
+      handler: async (args) => {
+        const linked = requireLinked(ctx);
+        if (!linked.ok)
+          return linked.error;
+        const { config: config3 } = linked;
+        const a = args;
+        if (a.question === undefined === (a.questionId === undefined)) {
+          return errorResult(new OpError("invalid_request", "Exactly one of question or questionId is required"));
+        }
+        const graphState = ctx.getGraphState();
+        if (graphState.kind === "error")
+          return errorResult(graphState.error);
+        const { index } = graphState;
+        const uniqueIds = [...new Set(a.sourceNodeIds)];
+        const unresolved = uniqueIds.filter((id) => !ctx.retrievalLog.has(id));
+        if (unresolved.length > 0) {
+          return errorResult(new OpError("invalid_request", `sourceNodeIds cites id(s) not returned by this session's graph_query/graph_node/graph_path: ${unresolved.join(", ")}`));
+        }
+        const sources = uniqueIds.map((id) => {
+          const projected = index.project(index.nodesById.get(id));
+          return { file: projected.sourceFile, location: projected.sourceLocation };
+        });
+        const footer = buildFooter(index.stamp, sources);
+        const fullContent = a.content + footer;
+        try {
+          const client = ctx.getNotexClient(config3);
+          let targetQuestionId;
+          let createdNewQuestion = false;
+          if (a.question !== undefined) {
+            const created = await client.createContext(config3.organizationId, config3.repositoryId, a.question);
+            targetQuestionId = created.id;
+            createdNewQuestion = true;
+          } else {
+            const existing = await client.getContext(config3.organizationId, a.questionId);
+            if (existing.repositoryId !== config3.repositoryId) {
+              return errorResult(new OpError("not_found", `Unknown Question id: ${a.questionId}`));
+            }
+            targetQuestionId = existing.id;
+          }
+          let file2;
+          try {
+            file2 = await client.createFile(config3.organizationId, targetQuestionId, {
+              name: a.name,
+              contentType: "text",
+              content: fullContent
+            });
+          } catch (fileErr) {
+            if (createdNewQuestion)
+              await client.deleteContext(config3.organizationId, targetQuestionId).catch(() => {});
+            throw fileErr;
+          }
+          const text = `Saved Answer "${file2.name}" (${file2.id}) to Question ${targetQuestionId}.`;
+          return { content: [{ type: "text", text }], structuredContent: { answerId: file2.id, questionId: targetQuestionId, footer } };
+        } catch (err) {
+          return fromNotexError(err);
+        }
+      }
     }
   };
 }
 
+// src/notexClient.ts
+var DEFAULT_API_URL = "http://localhost:3000";
+function resolveApiUrl(env = process.env) {
+  return env.NOTEX_API_URL?.trim() || DEFAULT_API_URL;
+}
+async function request(config3, fetchImpl, method, path2, body) {
+  let res;
+  try {
+    res = await fetchImpl(`${config3.baseUrl}${path2}`, {
+      method,
+      headers: {
+        "x-api-key": config3.apiKey,
+        ...body !== undefined ? { "content-type": "application/json" } : {}
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined
+    });
+  } catch (err) {
+    throw new OpError(ERROR_CODES.notexApiError, `Could not reach the Notex API at ${config3.baseUrl}`, err);
+  }
+  if (res.status === 401)
+    throw new OpError(ERROR_CODES.unauthorized, "Notex rejected the API key");
+  if (res.status === 403)
+    throw new OpError(ERROR_CODES.forbidden, "Not authorized for this Project");
+  if (res.status === 404)
+    throw new OpError(ERROR_CODES.notFound, "Not found in Notex");
+  if (!res.ok) {
+    const body2 = await res.json().catch(() => ({}));
+    throw new OpError(ERROR_CODES.notexApiError, body2.error?.message ?? `Notex API error (HTTP ${res.status})`);
+  }
+  return await res.json();
+}
+var enc = (id) => encodeURIComponent(id);
+function createNotexClient(config3, fetchImpl = fetch) {
+  return {
+    listContexts: (organizationId, repositoryId) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(repositoryId)}/contexts`),
+    getContext: (organizationId, id) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(id)}`),
+    createContext: (organizationId, repositoryId, question) => request(config3, fetchImpl, "POST", `/api/v1/organizations/${enc(organizationId)}/repositories/${enc(repositoryId)}/contexts`, { question }),
+    listFiles: (organizationId, contextId) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(contextId)}/files`),
+    getFile: (organizationId, id) => request(config3, fetchImpl, "GET", `/api/v1/organizations/${enc(organizationId)}/files/${enc(id)}`),
+    createFile: (organizationId, contextId, file2) => request(config3, fetchImpl, "POST", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(contextId)}/files`, file2),
+    deleteContext: (organizationId, id) => request(config3, fetchImpl, "DELETE", `/api/v1/organizations/${enc(organizationId)}/contexts/${enc(id)}`)
+  };
+}
+
 // src/notexConfig.ts
 import { readFileSync as readFileSync3 } from "node:fs";
 import { join as join2 } from "node:path";
@@ -33899,10 +34076,11 @@ function buildMcpServer(checkoutPath) {
     getCurrentHeadSha: createHeadShaCache(checkoutPath),
     getGraphState: () => graphState,
     getConfigState: () => loadNotexConfig(checkoutPath),
-    retrievalLog
+    retrievalLog,
+    getNotexClient: (config3) => createNotexClient({ baseUrl: resolveApiUrl(), apiKey: config3.apiKey })
   };
   const server = new McpServer({ name: "notex-companion", version: API_VERSION });
-  registerMcpTools(server, { ...createGraphTools(ctx), ...createNotexToolStubs(ctx) });
+  registerMcpTools(server, { ...createGraphTools(ctx), ...createNotexTools(ctx) });
   return server;
 }
 async function startMcpServer(checkoutPath) {

package/dist/client.js

@@ -4,7 +4,9 @@ var ERROR_CODES = {
   notFound: "not_found",
   graphUnreadable: "graph_unreadable",
   invalidRequest: "invalid_request",
-  graphLoading: "graph_loading"
+  graphLoading: "graph_loading",
+  forbidden: "forbidden",
+  notexApiError: "notex_api_error"
 };
 
 class OpError extends Error {

package/dist/index.js

@@ -4,7 +4,9 @@ var ERROR_CODES = {
   notFound: "not_found",
   graphUnreadable: "graph_unreadable",
   invalidRequest: "invalid_request",
-  graphLoading: "graph_loading"
+  graphLoading: "graph_loading",
+  forbidden: "forbidden",
+  notexApiError: "notex_api_error"
 };
 
 class OpError extends Error {
@@ -485,7 +487,9 @@ var ERROR_STATUS = {
   [ERROR_CODES.notFound]: 404,
   [ERROR_CODES.graphUnreadable]: 409,
   [ERROR_CODES.invalidRequest]: 422,
-  [ERROR_CODES.graphLoading]: 503
+  [ERROR_CODES.graphLoading]: 503,
+  [ERROR_CODES.forbidden]: 403,
+  [ERROR_CODES.notexApiError]: 502
 };
 function createHandler(opts) {
   return async (req) => {

package/dist/mcpTools.d.ts

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { OpError } from "./types.js";
 import type { GraphIndex } from "./graph.js";
-import type { NotexConfigState } from "./notexConfig.js";
+import type { NotexConfig, NotexConfigState } from "./notexConfig.js";
+import type { NotexClient } from "./notexClient.js";
 import type { RetrievalLog } from "./retrievalLog.js";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
@@ -21,6 +22,9 @@ export type McpToolContext = {
      * run mid-session without a restart. */
     getConfigState: () => NotexConfigState;
     retrievalLog: RetrievalLog;
+    /** Built fresh from the linked config on every notex_* call — a seam mcpTools.test.ts uses to
+     * inject a fake client, and the same "re-verify, don't cache" posture as getConfigState. */
+    getNotexClient: (config: NotexConfig) => NotexClient;
 };
 export type ToolDef = {
     description: string;
@@ -29,10 +33,4 @@ export type ToolDef = {
 };
 export declare function registerMcpTools(server: McpServer, tools: Record<string, ToolDef>): void;
 export declare function createGraphTools(ctx: McpToolContext): Record<string, ToolDef>;
-/**
- * Argument shapes only, per §2.3/§2.4 — every handler errors. The actual Notex Worker binding
- * (auth, requests, the retrieval-log-checked write) is TBR-72's job. What TBR-69 owes here is
- * §4.1's acceptance bar: the tools are listed, never hidden, and a missing/malformed
- * `.notex/notex.json` produces the documented actionable error rather than a stack trace.
- */
-export declare function createNotexToolStubs(ctx: McpToolContext): Record<string, ToolDef>;
+export declare function createNotexTools(ctx: McpToolContext): Record<string, ToolDef>;

package/dist/notexClient.d.ts

@@ -0,0 +1,43 @@
+export type NotexContext = {
+    id: string;
+    repositoryId: string;
+    question: string;
+    createdAt: string;
+};
+export type NotexFile = {
+    id: string;
+    contextId: string;
+    name: string;
+    contentType: "text" | "upload";
+    content: string;
+    createdAt: string;
+};
+export type NotexClientConfig = {
+    baseUrl: string;
+    apiKey: string;
+};
+type FetchImpl = typeof fetch;
+/** `NOTEX_API_URL` overrides the default — there is no production Notex origin baked into this
+ * package yet, and `.notex/notex.json` (notex-mcp-server.md §4) deliberately carries no URL. */
+export declare function resolveApiUrl(env?: {
+    NOTEX_API_URL?: string;
+}): string;
+export declare function createNotexClient(config: NotexClientConfig, fetchImpl?: FetchImpl): {
+    listContexts: (organizationId: string, repositoryId: string) => Promise<NotexContext[]>;
+    getContext: (organizationId: string, id: string) => Promise<NotexContext>;
+    createContext: (organizationId: string, repositoryId: string, question: string) => Promise<NotexContext>;
+    listFiles: (organizationId: string, contextId: string) => Promise<NotexFile[]>;
+    getFile: (organizationId: string, id: string) => Promise<NotexFile>;
+    createFile: (organizationId: string, contextId: string, file: {
+        name: string;
+        contentType: "text" | "upload";
+        content: string;
+    }) => Promise<NotexFile>;
+    /** Used only for best-effort rollback of a Question just created by notex_save_answer when
+     * its Answer write then fails — never exposed as its own MCP tool (§2.4/§9: no delete tool). */
+    deleteContext: (organizationId: string, id: string) => Promise<{
+        success: true;
+    }>;
+};
+export type NotexClient = ReturnType<typeof createNotexClient>;
+export {};

package/dist/types.d.ts

@@ -55,6 +55,11 @@ export declare const ERROR_CODES: {
     readonly graphUnreadable: "graph_unreadable";
     readonly invalidRequest: "invalid_request";
     readonly graphLoading: "graph_loading";
+    /** The Notex API rejected a request as 403 — key holder lacks Grant access to the Project. */
+    readonly forbidden: "forbidden";
+    /** Any other non-2xx from the Notex API (rate limit, 5xx, ...) — notex-mcp-server.md §4.1
+     * reuses this module's error vocabulary rather than inventing a second taxonomy. */
+    readonly notexApiError: "notex_api_error";
 };
 export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notex-companion",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Local retrieval companion for Notex — reads a checkout's graphify-out/graph.json and serves deterministic search/query/path/node lookups over loopback HTTP and MCP stdio. No LLM, no graph building, no network beyond 127.0.0.1.",
   "keywords": ["notex", "graphify", "mcp", "code-graph"],
   "license": "MIT",