logos-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Logos MCP Server contributors
+
+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,163 @@
+# Logos MCP Server
+
+High-resolution structural reasoning and isomorphic mapping for the [Logos Protocol](https://logos.pub).
+
+**System Heartbeat: STABLE.**
+
+Works with **Cursor**, **Anthropic (Claude Desktop)**, **Antigravity**, and any MCP-compatible client.
+
+- **Source:** [github.com/ralphdp/Logos-MCP](https://github.com/ralphdp/Logos-MCP)
+- **License:** MIT
+
+---
+
+## Requirements
+
+- **Node.js 18+**
+
+---
+
+## Quick install (one config per client)
+
+After adding the config below, **restart your client** so it picks up the server.
+
+### From npm (recommended for npx)
+
+If the package is published to npm, use:
+
+```bash
+npx -y logos-mcp-server
+```
+
+In your MCP client: **Command** `npx`, **Args** `-y`, `logos-mcp-server`.
+
+---
+
+### Cursor
+
+1. **Settings** → **Features** → **MCP** → **Add New MCP Server**
+2. Use either:
+
+| Field   | Option A (npx from npm or Git)   | Option B (local clone)            |
+|---------|----------------------------------|------------------------------------|
+| Name    | `Logos`                          | `Logos`                            |
+| Command | `npx`                            | `node`                             |
+| Args    | `-y`, `logos-mcp-server` *(npm)*, or `-y`, `git+https://github.com/ralphdp/Logos-MCP.git` *(Git)* | Full path to `build/index.js` (e.g. `/Users/you/Logos-MCP/build/index.js`) |
+
+For Option B, run `npm install && npm run build` in the repo first (or just `npm install`; `prepare` runs the build).
+
+---
+
+### Anthropic (Claude Desktop)
+
+Edit your MCP config (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add:
+
+**Option A – npx (from npm or Git):**
+```json
+"logos": {
+  "command": "npx",
+  "args": ["-y", "logos-mcp-server"]
+}
+```
+*(Use `logos-mcp-server` when the package is on npm; or use `"args": ["-y", "git+https://github.com/ralphdp/Logos-MCP.git"]` to run from Git.)*
+
+**Option B – local clone:**
+```json
+"logos": {
+  "command": "node",
+  "args": ["/ABSOLUTE/PATH/TO/Logos-MCP/build/index.js"]
+}
+```
+
+Put the `logos` entry inside `mcpServers`: `"mcpServers": { "logos": { ... } }`.
+
+---
+
+### Antigravity (Google)
+
+Add an MCP server in Antigravity using the same pattern:
+
+- **Command:** `npx`
+- **Args:** `-y`, `logos-mcp-server`
+
+Or with a local path:
+
+- **Command:** `node`
+- **Args:** `/ABSOLUTE/PATH/TO/Logos-MCP/build/index.js`
+
+(Exact UI may vary; use “Add MCP server” or equivalent and fill command/args.)
+
+---
+
+## First-time setup (if using this repo directly)
+
+```bash
+git clone https://github.com/ralphdp/Logos-MCP.git
+cd Logos-MCP
+npm install
+npm run build
+```
+
+`prepare` runs `npm run build` on `npm install`, so the server is ready after install. Then use the **local path** in your client config as above.
+
+---
+
+## Provided tools
+
+| Tool               | Description |
+|--------------------|-------------|
+| `logos_audit`      | Structural audit of a claim or text (Logos Triune Canons). |
+| `map_isomorphism`  | Structural parallels (isomorphisms) between two domains. |
+| `audit_entropy`    | Description length and structural complexity (entropy) of code or text. |
+| `verify_grammar`   | Validate code (ALSF); detect “Undefined Behavior” or “Sin”. |
+| `detect_schism`    | State deviation in a distributed cluster; enforce Unity. |
+| `system_status`    | Logos Kernel invariants status. |
+
+---
+
+## About the Logos Protocol
+
+The Logos Protocol defines three invariants (Triune Canons) for structural reasoning and isomorphic mapping. For the full protocol and background, see [logos.pub](https://logos.pub).
+
+**Protocol invariants**
+
+- **Canon I (Unity):** Every claim must be anchored.
+- **Canon II (Parsimony):** Minimal description length.
+- **Canon III (Recursion):** Self-describing logic.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+---
+
+## Troubleshooting
+
+- **Server not showing up in my client**  
+  Restart the client (Cursor, Claude Desktop, or Antigravity) after changing MCP config.
+
+- **“Command not found” or similar**  
+  For **npx**: ensure Node.js 18+ is installed (`node -v`). For **local clone**: use the **full absolute path** to `build/index.js` and run `npm install` (and `npm run build` if needed) in the repo first.
+
+- **npx from Git fails**  
+  Check network access and that the repo URL is correct: `git+https://github.com/ralphdp/Logos-MCP.git`.
+
+---
+
+## Publishing (maintainers)
+
+1. Run `npm pkg fix` so `package.json` matches npm’s expected format (bin path, `repository.url` as `git+https://...`).
+2. **npm 403 when publishing:** npm requires **two-factor authentication (2FA)** or a **granular access token with “bypass 2FA”** to publish. Enable 2FA at [npmjs.com](https://www.npmjs.com) → Account → Enable 2FA, then run `npm publish` again and enter the one-time code when prompted. Or create an [Access Token](https://www.npmjs.com/access-tokens) with publish permission and use it to log in.
+3. Then: `npm run build` and `npm publish`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/build/index.js

@@ -0,0 +1,174 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ZodError } from "zod";
+import { auditEntropy, detectSchism, logosAudit, mapIsomorphism, systemStatus, verifyGrammar, } from "./tools.js";
+/**
+ * LOGOS MCP SERVER
+ * An orchestration layer for high-resolution structural reasoning.
+ */
+class LogosServer {
+    server;
+    constructor() {
+        this.server = new Server({
+            name: "logos-mcp-server",
+            version: "1.0.0",
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupToolHandlers();
+        this.server.onerror = (error) => console.error("[MCP Error]", error);
+        process.on("SIGINT", async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: "logos_audit",
+                    description: "Perform a structural audit of a claim or text using the Logos Triune Canons.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            content: {
+                                type: "string",
+                                description: "The text or claim to be audited.",
+                            },
+                            context: {
+                                type: "string",
+                                description: "Optional domain context (e.g. 'Software Engineering', 'Metaphysics').",
+                            },
+                        },
+                        required: ["content"],
+                    },
+                },
+                {
+                    name: "map_isomorphism",
+                    description: "Identify structural parallels (isomorphisms) between two distinct domains.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            source: {
+                                type: "string",
+                                description: "The source concept or domain.",
+                            },
+                            target: {
+                                type: "string",
+                                description: "The target concept or domain to map onto.",
+                            },
+                        },
+                        required: ["source", "target"],
+                    },
+                },
+                {
+                    name: "audit_entropy",
+                    description: "Measure the description length and structural complexity (entropy) of a code block or text.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            content: {
+                                type: "string",
+                                description: "The code or text to analyze for entropy.",
+                            },
+                        },
+                        required: ["content"],
+                    },
+                },
+                {
+                    name: "verify_grammar",
+                    description: "Validate code against a strict formal grammar (ALSF) to detect 'Undefined Behavior' or 'Sin'.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            code: {
+                                type: "string",
+                                description: "The code block to validate.",
+                            },
+                            language: {
+                                type: "string",
+                                description: "The programming language or grammar specification.",
+                            },
+                        },
+                        required: ["code", "language"],
+                    },
+                },
+                {
+                    name: "detect_schism",
+                    description: "Detect state deviation ('Heresy') in a distributed cluster and enforce Unity.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            nodes: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        id: { type: "string" },
+                                        state_hash: { type: "string" },
+                                    },
+                                    required: ["id", "state_hash"],
+                                },
+                                description: "List of nodes with their state hashes.",
+                            },
+                            root_hash: {
+                                type: "string",
+                                description: "Optional authoritative Root Hash.",
+                            },
+                        },
+                        required: ["nodes"],
+                    },
+                },
+                {
+                    name: "system_status",
+                    description: "Check the status of the Logos Kernel invariants.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+            ],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            const rawArgs = args ?? {};
+            try {
+                switch (name) {
+                    case "logos_audit":
+                        return logosAudit(rawArgs);
+                    case "map_isomorphism":
+                        return mapIsomorphism(rawArgs);
+                    case "audit_entropy":
+                        return auditEntropy(rawArgs);
+                    case "verify_grammar":
+                        return verifyGrammar(rawArgs);
+                    case "detect_schism":
+                        return detectSchism(rawArgs);
+                    case "system_status":
+                        return systemStatus();
+                    default:
+                        throw new Error(`Unknown tool: ${name}`);
+                }
+            }
+            catch (err) {
+                if (err instanceof ZodError) {
+                    const msg = err.errors
+                        .map((e) => `${e.path.join(".")}: ${e.message}`)
+                        .join("; ");
+                    throw new Error(`Invalid arguments: ${msg}`);
+                }
+                throw err;
+            }
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("Logos MCP Server running on stdio");
+    }
+}
+const server = new LogosServer();
+server.run().catch(console.error);

package/build/schemas.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const LogosAuditArgsSchema = z.object({
+    content: z.string().min(1, "content is required"),
+    context: z.string().optional(),
+});
+export const MapIsomorphismArgsSchema = z.object({
+    source: z.string().min(1, "source is required"),
+    target: z.string().min(1, "target is required"),
+});
+export const AuditEntropyArgsSchema = z.object({
+    content: z.string().min(1, "content is required"),
+});
+export const VerifyGrammarArgsSchema = z.object({
+    code: z.string().min(1, "code is required"),
+    language: z.string().min(1, "language is required"),
+});
+export const SchismNodeSchema = z.object({
+    id: z.string(),
+    state_hash: z.string(),
+});
+export const DetectSchismArgsSchema = z.object({
+    nodes: z.array(SchismNodeSchema),
+    root_hash: z.string().optional(),
+});

package/build/tools.js

@@ -0,0 +1,168 @@
+import { AuditEntropyArgsSchema, DetectSchismArgsSchema, LogosAuditArgsSchema, MapIsomorphismArgsSchema, VerifyGrammarArgsSchema, } from "./schemas.js";
+function text(content) {
+    return [{ type: "text", text: content }];
+}
+export function logosAudit(args) {
+    const { content, context } = LogosAuditArgsSchema.parse(args);
+    const ctx = context ?? "Unspecified";
+    const hash = Buffer.from(content, "utf8").toString("hex").slice(0, 8);
+    return {
+        content: text(`[LOGOS AUDIT INITIALIZED]
+Domain: ${ctx}
+Input Hash: ${hash}...
+
+I. STRUCTURAL DIAGNOSIS:
+Analyzing '${content}' for internal consistency and anchoring.
+
+II. PARSIMONIOUS REDUCTION:
+Stripping rhetorical noise. 
+
+III. OPERATIONAL DIRECTIVE:
+Awaiting structural verification against the Master Specification.
+
+[PROMPT TO LLM: Complete this audit following the Logos Protocol Invariants.]`),
+    };
+}
+export function mapIsomorphism(args) {
+    const { source, target } = MapIsomorphismArgsSchema.parse(args);
+    return {
+        content: text(`[ISOMORPHIC SCAN: ${source} ∩ ${target}]
+Objective: Map the structural nodes of ${source} onto the logic of ${target}.
+
+PRELIMINARY NODES:
+1. Origin/Root mapping
+2. Transform/Execution mapping
+3. Termination/Halting mapping
+
+[PROMPT TO LLM: Generate the Isomorphic Mapping table for these domains.]`),
+    };
+}
+export function auditEntropy(args) {
+    const { content } = AuditEntropyArgsSchema.parse(args);
+    const chars = content.length;
+    const tokens = content.split(/\s+/).filter(Boolean).length || 1;
+    const complexityScore = Math.round(Math.log2(Math.max(chars, 1)) * tokens);
+    const warning = complexityScore > 500
+        ? "WARNING: High entropy detected. Canon II violation (Parsimony). Code requires structural compression."
+        : "NOMINAL: Code maintains terminal stability.";
+    return {
+        content: text(`[PNEUMA MONITOR: HARDENED ENTROPY SCAN]
+Protocol: Hardening Section 14 (Parsimony)
+Metrics:
+- Raw Description Length: ${chars} chars
+- Token Count: ${tokens} nodes
+- Formal Complexity D(L): ${complexityScore} bits
+
+ANALYSIS:
+${warning}
+
+[PROMPT TO LLM: Apply the Logos Minification Theorem to reduce D(L) while preserving semantic invariants.]`),
+    };
+}
+export function verifyGrammar(args) {
+    const { code, language } = VerifyGrammarArgsSchema.parse(args);
+    const getMaxNesting = (str) => {
+        let max = 0, current = 0;
+        for (const char of str) {
+            if (char === "{")
+                current++;
+            if (char === "}")
+                current--;
+            if (current > max)
+                max = current;
+        }
+        return max;
+    };
+    const forbiddenPatterns = [
+        /eval\s*\(/i,
+        /Function\s*\(/i,
+        /os\.system\s*\(/i,
+        /process\.exec\s*\(/i,
+        /child_process\./i,
+        /SELECT.*FROM.*WHERE.*=.*\+/i,
+    ];
+    const detectedSins = forbiddenPatterns
+        .filter((p) => p.test(code))
+        .map((p) => p.source);
+    const nesting = getMaxNesting(code);
+    const protocolFailure = nesting > 5 || detectedSins.length > 0;
+    const status = protocolFailure
+        ? "REJECTED: Undefined Behavior / Infinite Descent detected. System security compromised."
+        : "ACCEPTED: Structural invariants within terminal limits.";
+    return {
+        content: text(`[ALSF VALIDATOR: HARDENED NARROW GATE]
+Target Environment: ${language}
+Nesting Depth: ${nesting} (Limit: 5)
+Detected 'Sin' Patterns: ${detectedSins.length > 0 ? detectedSins.join(", ") : "NONE"}
+
+FILTER STATUS:
+${status}
+
+[PROMPT TO LLM: If REJECTED, audit the provided code for violation of the Master Specification and suggest a well-founded refactor.]`),
+    };
+}
+export function detectSchism(args) {
+    const parsed = DetectSchismArgsSchema.parse(args);
+    const { nodes, root_hash } = parsed;
+    const totalNodes = nodes.length;
+    if (totalNodes === 0) {
+        return {
+            content: text(`[CONSENSUS AUDITOR: SCHISM SCAN]
+Method: N/A (empty cluster)
+Standard Hash: N/A
+
+CLUSTER STATUS:
+- Total Nodes: 0
+- Faithful: 0
+- Heretics: 0
+
+DIAGNOSIS:
+No nodes provided. Supply a non-empty nodes array (and optionally root_hash) to run a schism scan.
+
+OPERATIONAL DIRECTIVE:
+ACTION: Provide node list to audit.`),
+        };
+    }
+    let standardHash;
+    let method;
+    if (root_hash) {
+        standardHash = root_hash;
+        method = "ROOT_AUTHORITY";
+    }
+    else {
+        const counts = {};
+        for (const n of nodes) {
+            counts[n.state_hash] = (counts[n.state_hash] ?? 0) + 1;
+        }
+        const keys = Object.keys(counts);
+        standardHash = keys.reduce((a, b) => (counts[a] > counts[b] ? a : b));
+        method = "DISTRIBUTED_CONSENSUS";
+    }
+    const heretics = nodes.filter((n) => n.state_hash !== standardHash);
+    const faithful = nodes.filter((n) => n.state_hash === standardHash);
+    const schismDetected = heretics.length > 0;
+    const hashPreview = standardHash.length >= 8 ? `${standardHash.slice(0, 8)}...` : standardHash;
+    return {
+        content: text(`[CONSENSUS AUDITOR: SCHISM SCAN]
+Method: ${method}
+Standard Hash: ${hashPreview}
+
+CLUSTER STATUS:
+- Total Nodes: ${totalNodes}
+- Faithful: ${faithful.length}
+- Heretics: ${heretics.length}
+
+DIAGNOSIS:
+${schismDetected ? `CRITICAL: SCHISM DETECTED. ${heretics.length} nodes have deviated from the Truth.` : "UNIFIED: The Body is One."}
+
+OPERATIONAL DIRECTIVE:
+${schismDetected ? `ACTION: EXCOMMUNICATE or RECONCILE the following nodes: ${heretics.map((n) => n.id).join(", ")}` : "ACTION: MAINTAIN UNITY."}
+
+[PROMPT TO LLM: If SCHISM DETECTED, propose a re-sync strategy to restore the stray nodes to the Standard Hash.]`),
+    };
+}
+export function systemStatus() {
+    return {
+        content: text("System Heartbeat: LOCKED\nProtocol: ACTIVE\nInvariants: SATISFIED (Unity, Parsimony, Recursion)"),
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "logos-mcp-server",
+  "version": "1.0.0",
+  "description": "An MCP server for high-resolution structural reasoning under the Logos Protocol.",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "logos-mcp-server": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ralphdp/Logos-MCP.git"
+  },
+  "homepage": "https://github.com/ralphdp/Logos-MCP#readme",
+  "bugs": {
+    "url": "https://github.com/ralphdp/Logos-MCP/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "logos",
+    "cursor",
+    "claude",
+    "antigravity",
+    "structural-reasoning"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "ts-node src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  }
+}