nocturnusai-mcp 0.3.11

package/LICENSE

@@ -0,0 +1,103 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Auctalis LLC.
+Licensed Work:        Nocturnus.AI
+                      The Licensed Work is (c) 2026 Auctalis LLC.
+Additional Use Grant: You may make non-production use of the Licensed Work,
+                      and you may make internal production use of the Licensed
+                      Work within your own organization.
+                      "Non-production use" means use for development, testing,
+                      evaluation, demonstration, and educational purposes.
+                      "Internal production use" means use of the Licensed Work
+                      in a production environment solely for your organization's
+                      own internal operations, where the Licensed Work is not
+                      offered, sold, or made available to third parties.
+                      The following uses require a separate commercial license
+                      from the Licensor: any use that directly or indirectly
+                      offers the Licensed Work or any substantial portion of
+                      its functionality to third parties as a commercial
+                      product, hosted service, managed service, embedded
+                      component, or value-added offering.
+Change Date:          Four years from the date of each version release, or
+                      2030-02-19 for the initial release, whichever comes first.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: licensing@nocturnus.ai
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+To specify as the Change License the GPL Version 2.0 or any later version,
+or a license that is compatible with GPL Version 2.0 or a later version,
+where "compatible" means that software provided under the Change License can
+be included in a program with software provided under GPL Version 2.0 or a
+later version. Licensor may specify additional Change Licenses without
+limitation.
+
+To either: (a) specify an additional grant of rights to use that does not
+impose any additional restriction on the right granted in this License, as
+the Additional Use Grant; or (b) insert the text "None" to specify a Change
+Date.
+
+Not to modify this License in any other way.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.

package/README.md

@@ -0,0 +1,67 @@
+# nocturnusai-mcp
+
+MCP stdio server for [NocturnusAI](https://nocturnus.ai/) — agent reasoning, memory, and token-optimized context for AI applications. Point any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) at a running NocturnusAI instance and get:
+
+- **Deterministic reasoning** — multi-step inference with proof chains, not LLM guessing
+- **Token-optimized context** — salience-ranked retrieval puts only the most relevant facts in your context window, cutting token waste
+- **Agent memory lifecycle** — temporal facts, auto-expiration, consolidation, and decay so long-running agents stay focused
+- **Truth maintenance** — automatic retraction of derived knowledge when premises change
+
+This package is a thin stdio shim. It forwards MCP requests to a NocturnusAI server's `/mcp` JSON-RPC endpoint. It does not include the server itself.
+
+## Quick start — run a NocturnusAI server
+
+The fastest way to get a server running locally:
+
+```bash
+docker run -d --name nocturnusai -p 9300:9300 ghcr.io/auctalis/nocturnusai:latest
+```
+
+Data persists to a named Docker volume. Point your MCP client at this instance via the config below.
+
+Alternatives: build from source (`./gradlew :nocturnusai-server:run` from [the repo](https://github.com/Auctalis/nocturnusai)) or deploy to your own infra.
+
+## Client configuration
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "nocturnusai": {
+      "command": "npx",
+      "args": ["-y", "nocturnusai-mcp"],
+      "env": {
+        "NOCTURNUSAI_URL": "http://localhost:9300"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+
+Same structure — most clients accept a `command` + `args` + `env` block.
+
+## Environment variables
+
+| Variable              | Default                  | Purpose                                           |
+| --------------------- | ------------------------ | ------------------------------------------------- |
+| `NOCTURNUSAI_URL`     | `http://localhost:9300`  | Base URL of the NocturnusAI server                |
+| `NOCTURNUSAI_API_KEY` | _(none)_                 | Sent as `X-API-Key` when set                      |
+| `NOCTURNUSAI_DATABASE`| `default`                | Sent as `X-Database` header                       |
+| `NOCTURNUSAI_TENANT`  | `default`                | Sent as `X-Tenant-ID` header                      |
+
+## What tools are available
+
+Whatever tools the upstream NocturnusAI server exposes. As of 0.3.x this includes `tell`, `ask`, `teach`, `forget`, `predicates`, `context`, `aggregate`, `bulk_assert`, `retract_pattern`, `fork_scope`, `merge_scope`, `list_scopes`, `delete_scope`. The shim is transparent — new tools added to the server appear automatically without a package update.
+
+## Design
+
+- `tools/list` and `tools/call` requests are forwarded via HTTP JSON-RPC 2.0 to `${NOCTURNUSAI_URL}/mcp`.
+- Tool schemas come from the upstream server. This package doesn't duplicate them.
+- Startup prints a warning to stderr if `/health` is unreachable so misconfig fails loudly.
+
+## License
+
+BUSL-1.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * NocturnusAI MCP stdio shim.
+ *
+ * Speaks MCP over stdio to an LLM client (Claude, Cursor, etc.) and forwards
+ * every tools/list and tools/call request to a NocturnusAI server's JSON-RPC
+ * /mcp endpoint over HTTP.
+ *
+ * Configuration via environment variables:
+ *   NOCTURNUSAI_URL       Base URL of NocturnusAI server (default: http://localhost:9300)
+ *   NOCTURNUSAI_API_KEY   Optional API key sent as X-API-Key
+ *   NOCTURNUSAI_DATABASE  Database name, sent as X-Database (default: default)
+ *   NOCTURNUSAI_TENANT    Tenant id,     sent as X-Tenant-ID (default: default)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const URL_BASE = (process.env.NOCTURNUSAI_URL ?? "http://localhost:9300").replace(/\/$/, "");
+const API_KEY = process.env.NOCTURNUSAI_API_KEY;
+const DATABASE = process.env.NOCTURNUSAI_DATABASE ?? "default";
+const TENANT = process.env.NOCTURNUSAI_TENANT ?? "default";
+let rpcId = 0;
+function headers() {
+    const h = {
+        "Content-Type": "application/json",
+        "X-Database": DATABASE,
+        "X-Tenant-ID": TENANT,
+    };
+    if (API_KEY)
+        h["X-API-Key"] = API_KEY;
+    return h;
+}
+async function rpc(method, params) {
+    const body = {
+        jsonrpc: "2.0",
+        id: ++rpcId,
+        method,
+        params: params ?? {},
+    };
+    const res = await fetch(`${URL_BASE}/mcp`, {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`NocturnusAI /mcp ${res.status} ${res.statusText}: ${text}`);
+    }
+    const json = (await res.json());
+    if (json.error) {
+        const msg = json.error.message || "upstream error";
+        throw new Error(`NocturnusAI RPC error ${json.error.code}: ${msg}`);
+    }
+    return json.result;
+}
+const server = new Server({
+    name: "nocturnusai-mcp",
+    version: "0.3.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const result = (await rpc("tools/list"));
+    return { tools: result.tools ?? [] };
+});
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const result = (await rpc("tools/call", {
+        name: req.params.name,
+        arguments: req.params.arguments ?? {},
+    }));
+    return {
+        content: result.content ?? [],
+        isError: result.isError,
+    };
+});
+async function main() {
+    // Quick connectivity check. Not fatal — a startup failure would hide behind
+    // the first tool call otherwise, which is confusing to debug.
+    try {
+        const res = await fetch(`${URL_BASE}/health`, { headers: headers() });
+        if (!res.ok) {
+            process.stderr.write(`[nocturnusai-mcp] warning: ${URL_BASE}/health returned ${res.status}\n`);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[nocturnusai-mcp] warning: cannot reach ${URL_BASE}: ${err.message}\n` +
+            `[nocturnusai-mcp] start the server or set NOCTURNUSAI_URL\n`);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[nocturnusai-mcp] fatal: ${err.stack ?? err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "nocturnusai-mcp",
+  "version": "0.3.11",
+  "description": "MCP stdio server for NocturnusAI — agent reasoning, memory lifecycle, and token-optimized context windows for AI applications.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "nocturnusai-mcp": "dist/index.js"
+  },
+  "mcpName": "ai.nocturnus/logic-server",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "nocturnusai",
+    "mcp",
+    "model-context-protocol",
+    "logic",
+    "inference",
+    "memory",
+    "reasoning",
+    "agent"
+  ],
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Auctalis/nocturnusai.git",
+    "directory": "sdks/mcp-server"
+  },
+  "homepage": "https://nocturnus.ai/",
+  "bugs": {
+    "url": "https://github.com/Auctalis/nocturnusai/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * NocturnusAI MCP stdio shim.
+ *
+ * Speaks MCP over stdio to an LLM client (Claude, Cursor, etc.) and forwards
+ * every tools/list and tools/call request to a NocturnusAI server's JSON-RPC
+ * /mcp endpoint over HTTP.
+ *
+ * Configuration via environment variables:
+ *   NOCTURNUSAI_URL       Base URL of NocturnusAI server (default: http://localhost:9300)
+ *   NOCTURNUSAI_API_KEY   Optional API key sent as X-API-Key
+ *   NOCTURNUSAI_DATABASE  Database name, sent as X-Database (default: default)
+ *   NOCTURNUSAI_TENANT    Tenant id,     sent as X-Tenant-ID (default: default)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const URL_BASE = (process.env.NOCTURNUSAI_URL ?? "http://localhost:9300").replace(/\/$/, "");
+const API_KEY = process.env.NOCTURNUSAI_API_KEY;
+const DATABASE = process.env.NOCTURNUSAI_DATABASE ?? "default";
+const TENANT = process.env.NOCTURNUSAI_TENANT ?? "default";
+
+let rpcId = 0;
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Database": DATABASE,
+    "X-Tenant-ID": TENANT,
+  };
+  if (API_KEY) h["X-API-Key"] = API_KEY;
+  return h;
+}
+
+async function rpc(method: string, params?: unknown): Promise<unknown> {
+  const body = {
+    jsonrpc: "2.0",
+    id: ++rpcId,
+    method,
+    params: params ?? {},
+  };
+  const res = await fetch(`${URL_BASE}/mcp`, {
+    method: "POST",
+    headers: headers(),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`NocturnusAI /mcp ${res.status} ${res.statusText}: ${text}`);
+  }
+  const json = (await res.json()) as {
+    result?: unknown;
+    error?: { code: number; message: string; data?: unknown };
+  };
+  if (json.error) {
+    const msg = json.error.message || "upstream error";
+    throw new Error(`NocturnusAI RPC error ${json.error.code}: ${msg}`);
+  }
+  return json.result;
+}
+
+const server = new Server(
+  {
+    name: "nocturnusai-mcp",
+    version: "0.3.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const result = (await rpc("tools/list")) as { tools: unknown[] };
+  return { tools: result.tools ?? [] };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const result = (await rpc("tools/call", {
+    name: req.params.name,
+    arguments: req.params.arguments ?? {},
+  })) as { content: unknown[]; isError?: boolean };
+  return {
+    content: result.content ?? [],
+    isError: result.isError,
+  };
+});
+
+async function main(): Promise<void> {
+  // Quick connectivity check. Not fatal — a startup failure would hide behind
+  // the first tool call otherwise, which is confusing to debug.
+  try {
+    const res = await fetch(`${URL_BASE}/health`, { headers: headers() });
+    if (!res.ok) {
+      process.stderr.write(
+        `[nocturnusai-mcp] warning: ${URL_BASE}/health returned ${res.status}\n`
+      );
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[nocturnusai-mcp] warning: cannot reach ${URL_BASE}: ${(err as Error).message}\n` +
+        `[nocturnusai-mcp] start the server or set NOCTURNUSAI_URL\n`
+    );
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[nocturnusai-mcp] fatal: ${(err as Error).stack ?? err}\n`);
+  process.exit(1);
+});