@learningnodes/elen-mcp 0.1.2

package/mcp_test_output.txt

@@ -0,0 +1,107 @@
+
+ RUN  v2.1.9 C:/Users/ln_ni/OneDrive/Desktop/Desktop/ventures/learningnodes/git/marketplace-repos/Elen/packages/mcp-server
+
+ Γ£ô tests/tools.test.ts > MCP tool schemas > tool descriptions match expected format
+ Γ£ô tests/tools.test.ts > MCP tool schemas > elen_log_decision schema has required fields
+ Γ£ô tests/tools.test.ts > MCP tool schemas > elen_search_precedents schema includes optional filters
+ Γ£ô tests/tools.test.ts > MCP tool schemas > elen_get_competency schema supports optional agentId
+ Γ£ô tests/tools.test.ts > MCP tool handlers > elen_log_decision creates a record via SDK
+ Γ£ô tests/tools.test.ts > MCP tool handlers > elen_search_precedents returns matching records
+ Γ£ô tests/tools.test.ts > MCP tool handlers > elen_get_competency returns profile
+ Γ£ô tests/tools.test.ts > MCP tool handlers > throws on invalid tool inputs
+ Γ£ô tests/server.test.ts > MCP server CLI > parses --agent-id and --storage args
+ × tests/server.test.ts > MCP server CLI > uses defaults when args are omitted
+   → expected 'C:\Users\ln_ni\.elen\decisions.db' to contain '.elen/decisions.db'
+ × tests/server.test.ts > routeToolCall > routes known tools and throws for unknown tool
+   → expected { record_id: 'rec-1', …(1) } to deeply equal { record_id: 'rec-1' }
+
+node.exe : ⎯⎯⎯⎯⎯⎯⎯ 
+Failed Tests 2 
+⎯⎯⎯⎯⎯⎯⎯
+At C:\Users\ln_ni\AppData\Roaming\npm\npx.ps1:24 
+char:5
++     & "node$exe"  
+"$basedir/node_modules/npm/bin/npx-cli.js" $args
++     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
+    + CategoryInfo          : NotSpecified: ([3 
+   1mΓÄ»ΓÄ»ΓÄ»Γ...»ΓÄ»ΓÄ»ΓÄ»:String) [], R  
+  emoteException
+    + FullyQualifiedErrorId : NativeCommandError
+ 
+
+ FAIL  
+tests/server.test.ts > MCP server 
+CLI > uses defaults when args are 
+omitted
+AssertionError: expected 
+'C:\Users\ln_ni\.elen\decisions.db' to contain 
+'.elen/decisions.db'
+
+Expected: ".elen/decisions.db"
+Received: "C:\Users\ln_ni\.elen
+\decisions.db"
+
+ Γ¥» 
+tests/server.test.ts:17:34
+     15| 
+     16|     expect(parsed[3
+3m.agentId).toBe('d
+efault-agent');
+     17|     expect(defa
+ultStoragePath()).toContain[
+39m('.elen/decisions.db');
+       |                               
+   ^
+     18|     expect(parsed[3
+3m.storagePath).toBeUndefined
+();
+     19|   });
+
+ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»Γ
+Ä»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»[1/2]ΓÄ»[39
+m
+
+ FAIL  
+tests/server.test.ts > 
+routeToolCall > routes known tools 
+and throws for unknown tool
+AssertionError: expected { 
+record_id: 'rec-1', …(1) } to deeply equal { 
+record_id: 'rec-1' }
+
+- Expected
++ Received
+
+  Object {
++   "next_suggested_action": "Decision 
+recorded. Consider using elen_search_precedents 
+to find related prior decisions before your next 
+choice.",
+    "record_id": "rec-1",
+  }
+
+ Γ¥» 
+tests/server.test.ts:30:5
+     28|     } as 
+any;
+     29| 
+     30|     await expec
+t(routeToolCall(elen, 
+'agent-a', 
+'elen_log_decision', {
+       |     ^
+     31|       question: 
+'Q',
+     32|       domain: 
+'infrastructure',
+
+ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»Γ
+Ä»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»ΓÄ»[2/2]ΓÄ»[39
+m
+
+ Test Files  1 failed | 1 passed (2)
+      Tests  2 failed | 9 passed (11)
+   Start at  12:20:16
+   Duration  6.93s (transform 3.40s, setup 0ms, collect 7.36s, tests 99ms, environment 5ms, prepare 2.00s)
+

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@learningnodes/elen-mcp",
+  "version": "0.1.2",
+  "license": "AGPL-3.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "elen-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@learningnodes/elen": "file:../sdk-ts",
+    "@modelcontextprotocol/sdk": "^1.17.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { createMcpServer, defaultStoragePath } from './server';
+
+// MCP SDK overrides the ambient `process` type, stripping cwd().
+// We use execSync as a workaround.
+const currentDir = (): string => execSync('cd', { encoding: 'utf-8' }).trim();
+
+export interface CliOptions {
+  agentId: string;
+  projectId: string;
+  storagePath?: string;
+}
+
+/**
+ * Auto-detect project identity from the environment.
+ * Priority: git remote name > package.json name > cwd basename > 'default'
+ */
+function detectProject(): string {
+  // 1. Try git remote URL → extract repo name
+  try {
+    const remote = execSync('git remote get-url origin', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    // https://github.com/org/repo-name.git → repo-name
+    // git@github.com:org/repo-name.git → repo-name
+    const match = remote.match(/[/:]([^/]+?)(?:\.git)?$/);
+    if (match?.[1]) return match[1];
+  } catch {
+    // Not a git repo or git not available
+  }
+
+  // 2. Try package.json name
+  const pkgPath = resolve(currentDir(), 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.name) {
+        // Strip scope: @org/name → name
+        return pkg.name.replace(/^@[^/]+\//, '');
+      }
+    } catch {
+      // Malformed package.json
+    }
+  }
+
+  // 3. Working directory basename
+  return basename(currentDir()) || 'default';
+}
+
+export function parseCliArgs(argv: string[]): CliOptions {
+  let agentId = 'default-agent';
+  let projectId: string | undefined;
+  let storagePath: string | undefined;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--agent-id') {
+      agentId = argv[i + 1] ?? agentId;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--project') {
+      projectId = argv[i + 1] ?? projectId;
+      i += 1;
+      continue;
+    }
+
+    if (arg === '--storage') {
+      storagePath = argv[i + 1] ?? storagePath;
+      i += 1;
+    }
+  }
+
+  return {
+    agentId,
+    projectId: projectId ?? detectProject(),
+    storagePath
+  };
+}
+
+async function main() {
+  const options = parseCliArgs(process.argv.slice(2));
+
+  process.stderr.write(`✦ Elen MCP starting — agent: ${options.agentId}, project: ${options.projectId}\n`);
+
+  const server = createMcpServer({
+    agentId: options.agentId,
+    projectId: options.projectId,
+    storagePath: options.storagePath ?? defaultStoragePath()
+  });
+
+  await server.start();
+}
+
+if (require.main === module) {
+  main().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Failed to start @learningnodes/elen-mcp: ${message}\n`);
+    process.exit(1);
+  });
+}

package/src/server.ts

@@ -0,0 +1,116 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Elen } from '@learningnodes/elen';
+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 {
+  elenCommitTool,
+  elenSuggestTool,
+  elenExpandTool,
+  elenSupersedeTool,
+  elenGetCompetencyTool,
+  elenLogDecisionTool,
+  elenSearchPrecedentsTool,
+  handleCommit,
+  handleSuggest,
+  handleExpand,
+  handleSupersede,
+  handleGetCompetency,
+  handleLogDecision,
+  handleSearchPrecedents
+} from './tools';
+
+export interface McpServerOptions {
+  agentId: string;
+  projectId?: string;
+  storagePath?: string;
+}
+
+export function defaultStoragePath(): string {
+  return join(homedir(), '.elen', 'decisions.db');
+}
+
+export function createElenClient(options: McpServerOptions): Elen {
+  const sqlitePath = options.storagePath ?? defaultStoragePath();
+  mkdirSync(dirname(sqlitePath), { recursive: true });
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return new Elen({
+    agentId: options.agentId,
+    projectId: options.projectId,
+    storage: 'sqlite' as const,
+    sqlitePath
+  } as any);
+}
+
+export async function routeToolCall(elen: Elen, agentId: string, name: string, args: unknown): Promise<unknown> {
+  switch (name) {
+    case elenCommitTool.name:
+      return handleCommit(elen, args);
+    case elenSuggestTool.name:
+      return handleSuggest(elen, args);
+    case elenExpandTool.name:
+      return handleExpand(elen, args);
+    case elenSupersedeTool.name:
+      return handleSupersede(elen, args);
+    case elenGetCompetencyTool.name:
+      return handleGetCompetency(elen, args, agentId);
+    case elenLogDecisionTool.name:
+      return handleLogDecision(elen, args);
+    case elenSearchPrecedentsTool.name:
+      return handleSearchPrecedents(elen, args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export function createMcpServer(options: McpServerOptions) {
+  const elen = createElenClient(options);
+
+  const server = new Server(
+    {
+      name: '@learningnodes/elen-mcp',
+      version: '0.1.0'
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      elenCommitTool,
+      elenSuggestTool,
+      elenExpandTool,
+      elenSupersedeTool,
+      elenGetCompetencyTool,
+      elenLogDecisionTool,
+      elenSearchPrecedentsTool
+    ]
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await routeToolCall(elen, options.agentId, request.params.name, request.params.arguments);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  });
+
+  return {
+    server,
+    async start() {
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+    }
+  };
+}

package/src/shims.d.ts

@@ -0,0 +1,41 @@
+declare module '@modelcontextprotocol/sdk/server/index.js' {
+  export class Server {
+    constructor(info: { name: string; version: string }, options: { capabilities: { tools: Record<string, never> } });
+    setRequestHandler(schema: unknown, handler: (request: any) => Promise<any>): void;
+    connect(transport: unknown): Promise<void>;
+  }
+}
+
+declare module '@modelcontextprotocol/sdk/server/stdio.js' {
+  export class StdioServerTransport { }
+}
+
+declare module '@modelcontextprotocol/sdk/types.js' {
+  export const ListToolsRequestSchema: unknown;
+  export const CallToolRequestSchema: unknown;
+}
+
+declare module 'node:fs' {
+  export function mkdirSync(path: string, options?: { recursive?: boolean }): void;
+}
+
+declare module 'node:os' {
+  export function homedir(): string;
+}
+
+declare module 'node:path' {
+  export function dirname(path: string): string;
+  export function join(...parts: string[]): string;
+}
+
+declare const require: {
+  main?: unknown;
+};
+
+declare const module: unknown;
+
+declare const process: {
+  argv: string[];
+  stderr: { write: (message: string) => void };
+  exit: (code?: number) => never;
+};

package/src/tools/commit.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { Elen } from '@learningnodes/elen';
+
+export const elenCommitTool = {
+    name: 'elen_commit',
+    description: 'Commit a new minimal epistemic decision to the graph. Pass constraints as plain text array.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: { type: 'string', description: 'The question or problem statement' },
+            domain: { type: 'string', description: 'Domain of decision (e.g. infrastructure, product)' },
+            decisionText: { type: 'string', description: 'The proposed answer/decision made' },
+            constraints: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Plain-text constraint rules (e.g. "budget < 500 tokens")'
+            },
+            refs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Explicit pointers to other decision IDs or artifacts'
+            }
+        },
+        required: ['question', 'domain', 'decisionText', 'constraints']
+    }
+};
+
+export const commitInputSchema = z.object({
+    question: z.string().min(1),
+    domain: z.string().min(1),
+    decisionText: z.string().min(1),
+    constraints: z.array(z.string().min(1)),
+    refs: z.array(z.string()).optional()
+});
+
+export async function handleCommit(elen: Elen, args: unknown): Promise<unknown> {
+    const parsed = commitInputSchema.parse(args);
+    const result = await elen.commitDecision(parsed);
+    return result;
+}

package/src/tools/competency.ts

@@ -0,0 +1,40 @@
+import type { Elen } from '@learningnodes/elen';
+
+export const elenGetCompetencyTool = {
+  name: 'elen_get_competency',
+  description:
+    'View the competency profile for this agent — domain expertise based on validated decision history.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      agentId: { type: 'string', description: 'Agent ID (defaults to current agent)' }
+    }
+  }
+} as const;
+
+export function validateCompetencyInput(input: unknown): { agentId?: string } {
+  if (input === undefined) {
+    return {};
+  }
+
+  if (!input || typeof input !== 'object') {
+    throw new Error('Invalid input: expected object');
+  }
+
+  const candidate = input as Record<string, unknown>;
+  if (candidate.agentId !== undefined && typeof candidate.agentId !== 'string') {
+    throw new Error('Invalid input: agentId must be a string');
+  }
+
+  return { agentId: candidate.agentId as string | undefined };
+}
+
+export async function handleGetCompetency(elen: Elen, args: unknown, defaultAgentId: string): Promise<unknown> {
+  const parsed = validateCompetencyInput(args);
+
+  if (parsed.agentId && parsed.agentId !== defaultAgentId) {
+    throw new Error('Cross-agent profile lookup is not supported by this MCP server');
+  }
+
+  return elen.getCompetencyProfile();
+}

package/src/tools/expand.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { Elen } from '@learningnodes/elen';
+
+export const elenExpandTool = {
+    name: 'elen_expand',
+    description: 'Expand a minimal pointer decision ID into its full constraints and text when ambiguity requires it.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            decisionId: { type: 'string', description: 'The decision_id (e.g. dec:INFA-aBcDeF) to expand' }
+        },
+        required: ['decisionId']
+    }
+};
+
+export const expandInputSchema = z.object({
+    decisionId: z.string().min(1)
+});
+
+export async function handleExpand(elen: Elen, args: unknown): Promise<unknown> {
+    const parsed = expandInputSchema.parse(args);
+    const result = await elen.expand(parsed.decisionId);
+    return result;
+}

package/src/tools/index.ts

@@ -0,0 +1,23 @@
+export { elenCommitTool, handleCommit, commitInputSchema } from './commit';
+export { elenSuggestTool, handleSuggest, suggestInputSchema } from './suggest';
+export { elenExpandTool, handleExpand, expandInputSchema } from './expand';
+export { elenSupersedeTool, handleSupersede, supersedeInputSchema } from './supersede';
+export { elenGetCompetencyTool, handleGetCompetency, validateCompetencyInput } from './competency';
+export {
+  elenLogDecisionTool,
+  elenSearchPrecedentsTool,
+  handleLogDecision,
+  handleSearchPrecedents,
+  validateLogDecisionInput,
+  validateSearchInput
+} from './legacy';
+
+export const ELEN_TOOLS = [
+  'elen_commit',
+  'elen_suggest',
+  'elen_expand',
+  'elen_supersede',
+  'elen_get_competency',
+  'elen_log_decision',
+  'elen_search_precedents'
+] as const;

package/src/tools/legacy.ts

@@ -0,0 +1,88 @@
+import type { Elen } from '@learningnodes/elen';
+
+export const elenLogDecisionTool = {
+  name: 'elen_log_decision',
+  description: 'Create a validated Decision Record from constraints/evidence/answer.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      question: { type: 'string' },
+      domain: { type: 'string' },
+      constraints: { type: 'array', items: { type: 'string' } },
+      evidence: { type: 'array', items: { type: 'string' } },
+      answer: { type: 'string' },
+      parentPrompt: { type: 'string' }
+    },
+    required: ['question', 'constraints', 'evidence', 'answer']
+  }
+} as const;
+
+export const elenSearchPrecedentsTool = {
+  name: 'elen_search_precedents',
+  description: 'Search validated decisions for precedents.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      domain: { type: 'string' },
+      minConfidence: { type: 'number' },
+      limit: { type: 'number' }
+    }
+  }
+} as const;
+
+export function validateLogDecisionInput(input: unknown) {
+  if (!input || typeof input !== 'object') throw new Error('missing required field: question');
+  const candidate = input as Record<string, unknown>;
+  for (const field of ['question', 'constraints', 'evidence', 'answer']) {
+    if (!(field in candidate)) throw new Error(`missing required field: ${field}`);
+  }
+  return candidate as {
+    question: string;
+    domain?: string;
+    constraints: string[];
+    evidence: string[];
+    answer: string;
+    parentPrompt?: string;
+  };
+}
+
+export function validateSearchInput(input: unknown): {
+  query?: string;
+  domain?: string;
+  minConfidence?: number;
+  limit?: number;
+} {
+  if (!input) return {};
+  if (typeof input !== 'object') throw new Error('invalid search input');
+  const c = input as Record<string, unknown>;
+  if (c.limit !== undefined && typeof c.limit !== 'number') throw new Error('limit must be a number');
+  if (c.minConfidence !== undefined && typeof c.minConfidence !== 'number') {
+    throw new Error('minConfidence must be a number');
+  }
+  return c as { query?: string; domain?: string; minConfidence?: number; limit?: number };
+}
+
+export async function handleLogDecision(elen: Elen, args: unknown): Promise<unknown> {
+  const parsed = validateLogDecisionInput(args);
+  const result = await elen.logDecision({
+    question: parsed.question,
+    domain: parsed.domain ?? 'general',
+    constraints: parsed.constraints,
+    evidence: parsed.evidence,
+    answer: parsed.answer,
+    parentPrompt: parsed.parentPrompt
+  });
+
+  return { ...result, next_suggested_action: 'Use elen_search_precedents to discover related decisions.' };
+}
+
+export async function handleSearchPrecedents(elen: Elen, args: unknown): Promise<unknown> {
+  const parsed = validateSearchInput(args);
+  return elen.searchRecords({
+    query: parsed.query,
+    domain: parsed.domain,
+    minConfidence: parsed.minConfidence,
+    limit: parsed.limit
+  });
+}

package/src/tools/suggest.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { Elen } from '@learningnodes/elen';
+
+export const elenSuggestTool = {
+    name: 'elen_suggest',
+    description: 'Before making a decision or taking action, retrieve pointer-first minimal candidates of prior decisions.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Search term or question' },
+            domain: { type: 'string', description: 'Filter by domain' },
+            limit: { type: 'number', description: 'Max suggestions to return (Top-K)' }
+        },
+        required: ['query']
+    }
+};
+
+export const suggestInputSchema = z.object({
+    query: z.string().min(1),
+    domain: z.string().optional(),
+    limit: z.number().int().min(1).max(50).optional().default(5)
+});
+
+export async function handleSuggest(elen: Elen, args: unknown): Promise<unknown> {
+    const parsed = suggestInputSchema.parse(args);
+    const results = await elen.suggest({
+        query: parsed.query,
+        domain: parsed.domain,
+        limit: parsed.limit
+    });
+    return results;
+}