Mnemonica Strategy

MCP (Model Context Protocol) server for Mnemonica runtime analysis via Chrome Debug Protocol.

Overview

Strategy connects to running Node.js applications via Chrome Debug Protocol to extract and analyze Mnemonica type hierarchies. It compares runtime types with Tactica-generated types to validate and improve static analysis.

Installation

npm install @mnemonica/strategy

Usage

Prerequisites

Your target application must be running with the debug flag:

# For NestJS
nest start --debug --watch

# For regular Node.js
node --inspect=9229 your-app.js

As MCP Server

npx @mnemonica/strategy

Configure with Roo Code

Add to .roo/mcp.json:

{
	"mcpServers": {
		"mnemonica-strategy": {
			"command": "node",
			"args": ["/code/mnemonica/strategy/lib/cli.js"]
		}
	}
}

MCP Tools Provided

The Strategy MCP server exposes 3 bundled tools:

1. execute

Execute any command from the 3 context folders (MCP, RPC, RUN).

Input:

• context (string, required): Execution context - "MCP", "RPC", or "RUN"
• command (string, required): Command name to execute
• message (string, optional): JSON string containing command arguments

Example:

// Connect to NestJS debugger
execute {
  context: "RPC",
  command: "connection",
  message: "{ \"action\": \"connect\", \"host\": \"localhost\", \"port\": 9229 }"
}

// Check connection status
execute {
  context: "RPC",
  command: "connection",
  message: "{ \"action\": \"status\" }"
}

// Get runtime types
execute {
  context: "RPC",
  command: "get_runtime_types",
  message: "{}"
}

2. list

List available commands by context.

Input:

• context (string, required): "MCP", "RPC", "RUN", or "ALL"

Example:

list { context: "ALL" }

3. help

Get detailed help for any command.

Input:

• context (string, required): Command context
• command (string, required): Command name

Example:

help { context: "RPC", command: "connection" }

Args Passing Mechanism (IMPORTANT)

Due to MCP protocol limitations, command arguments must be passed as a JSON string in the message field, not as direct object properties.

Correct format:

execute {
  context: "RPC",
  command: "connection",
  message: "{ \"action\": \"connect\", \"host\": \"localhost\", \"port\": 9229 }"
}

Incorrect format (will not work):

// DON'T DO THIS
execute {
  context: "RPC",
  command: "connection",
  args: { action: "connect" }  // This won't work!
}

Common Commands

Connection Management

// Connect to Node.js debugger
execute {
  context: "RPC",
  command: "connection",
  message: "{ \"action\": \"connect\", \"host\": \"localhost\", \"port\": 9229 }"
}

// Check connection status
execute {
  context: "RPC",
  command: "connection",
  message: "{ \"action\": \"status\" }"
}

// Disconnect from runtime
execute {
  context: "RPC",
  command: "connection",
  message: "{ \"action\": \"disconnect\" }"
}

Type Analysis

// Get runtime types from connected application
execute {
  context: "RPC",
  command: "get_runtime_types",
  message: "{}"
}

// Analyze type hierarchy via CDP (retrieves complete type tree from NestJS)
execute {
  context: "MCP",
  command: "cdp_analyze_type_hierarchy",
  message: "{}"
}

// Create type in NestJS via CDP
execute {
  context: "MCP",
  command: "cdp_create_type",
  message: "{ \"typeName\": \"MyType\" }"
}

// Load Tactica-generated types
execute {
  context: "MCP",
  command: "load_remote_tactica_types",
  message: "{ \"projectPath\": \"/path/to/project\" }"
}

// Compare runtime vs Tactica types
execute {
  context: "MCP",
  command: "compare_with_tactica",
  message: "{ \"projectPath\": \"/path/to/project\" }"
}

Memory Management

// Store memory in connected runtime
execute {
  context: "RPC",
  command: "store_memory",
  message: "{ \"key\": \"myKey\", \"data\": { ... } }"
}

// Recall memories
execute {
  context: "RPC",
  command: "recall_memories",
  message: "{ \"key\": \"myKey\" }"
}

Example Workflow

1. Start your application with debug mode:

   cd tactica-examples/nestjs
   npm run start:debug
   

2. Connect to the debugger:

   execute {
     context: "RPC",
     command: "connection",
     message: "{ \"action\": \"connect\" }"
   }
   

3. Analyze runtime types:

   execute {
     context: "RPC",
     command: "get_runtime_types",
     message: "{}"
   }
   

4. Compare with Tactica-generated types:

   execute {
     context: "MCP",
     command: "compare_with_tactica",
     message: "{ \"projectPath\": \"/path/to/project\" }"
   }
   

Command Contexts

Context	Folder	Execution Environment
MCP	commands-mcp/	Local MCP server process
RPC	commands-rpc/	Remote via CDP in target Node.js
RUN	commands-run/	HTTP endpoint in VS Code

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Test
npm run test

CDP Scripts Architecture

The cdp-scripts/ folder contains scripts that execute inside the target Node.js runtime via Chrome Debug Protocol:

cdp-scripts/
├── create-type.js          # Creates mnemonica types in NestJS
└── analyze-hierarchy.js    # Retrieves complete type hierarchy

How it works:

1. MCP command reads the script file
2. Injects var args = {...} at the top with command arguments
3. Sends to NestJS via client.Runtime.evaluate({ expression: script })
4. Script executes in isolated VM context inside NestJS
5. Console.log output appears in NestJS terminal (not MCP output)
6. Return value is sent back to MCP

Key patterns for CDP scripts:

// Use process.mainModule.require (not require) because CDP runs in isolated VM
var mnemonica = process.mainModule.require('mnemonica');

// Access types via subtypes Map (avoids proxy enumeration issues)
defaultCollection.subtypes.forEach(function (Type, name) {
    // Process each type
});

// Recursive traversal for subtype hierarchy
function getSubtypes (Type) {
    var subtypes = [];
    Type.subtypes.forEach(function (SubType, name) {
        subtypes.push({
            name: name,
            subtypes: getSubtypes(SubType)  // Recursive
        });
    });
    return subtypes;
}

Creating Commands

Commands are JavaScript files in the commands-*/ folders with MCP Tool Metadata:

/**
 * MCP Tool Metadata:
 * {
 *   "name": "my_command",
 *   "description": "What this command does",
 *   "inputSchema": {
 *     "type": "object",
 *     "properties": {
 *       "argName": { "type": "string" }
 *     }
 *   }
 * }
 */

var { require, args, store } = ctx;

// Parse message if present
var commandArgs = args;
if (args.message && typeof args.message === 'string') {
  try {
    commandArgs = JSON.parse(args.message);
  } catch (e) {
    return { success: false, error: 'Invalid JSON: ' + e.message };
  }
}

// Access parsed arguments
var myArg = commandArgs.argName;

// Return result
return { success: true, data: { ... } };

License

MIT