README

This is a repository for the MCPforEXP project. The project aims to create a conversational interface for Manifold.

Project Structure

The project is structured to clearly separate concerns and support scalability and testing. Source code lives under src/, with backend logic divided between server functionality and LLM/MCP integration, and the UI isolated in its own directory. Tests mirror the source structure under test/, making it easy to locate and maintain test coverage alongside corresponding components. Supporting scripts are kept in scripts/ to keep automation and tooling separate from application logic. This layout was chosen to improve readability, encourage modular development, and make the system easier to extend as the MCP and LLM integrations evolve.

├── scripts/
├── src/
│   ├── backend/
│   │   ├── mcp-server/
│   │   ├── utility/
│   │   └── llm/
│   ├── mcp-client/
│   └── frontend/
├── test/
│   ├── backend/
│   │   ├── server/
│   │   ├── llm/
│   │   └── mcp/
│   └── ui/

Usage

This project comes with convenient npm scripts to manage setup, teardown, and tests.

Install Dependencies

Make sure you’ve installed project dependencies:

npm install

Setup

Run the full project setup. This will install the manifold ruleset to the pico. After running the setup script you can then start the pico engine at will.

npm run setup
pico-engine

The npm run setup command runs the scripts/setup.sh script.

Teardown

Stop servers and clean up any temporary processes or files:

npm run teardown

This runs the scripts/teardown.sh script.

Running Tests

To run the Jest test suite:

npm test

Or equivalently:

npm run test

Uniform JSON for MCP ↔ KRL (events + queries)

This repo includes a small adapter that normalizes all pico-engine calls (KRL queries + events) into a single JSON envelope.

Request envelope

Use this shape for every operation:

{
  "id": "optional-correlation-id",
  "target": { "eci": "ECI_HERE" },
  "op": {
    "kind": "query",
    "rid": "io.picolabs.manifold_pico",
    "name": "getThings"
  },
  "args": {}
}

• Queries use op.kind="query" with op.rid + op.name
• Events use op.kind="event" with op.domain + op.type
• Args are always an object (query args or event attrs)

Response envelope

Success:

{
  "id": "optional-correlation-id",
  "ok": true,
  "data": {},
  "meta": {
    "kind": "query",
    "eci": "ECI_HERE",
    "rid": "io.picolabs.manifold_pico",
    "name": "getThings",
    "httpStatus": 200
  }
}

Error:

{
  "id": "optional-correlation-id",
  "ok": false,
  "error": {
    "code": "HTTP_ERROR",
    "message": "Upstream returned HTTP 500",
    "details": {}
  },
  "meta": {
    "kind": "query",
    "eci": "ECI_HERE",
    "rid": "io.picolabs.manifold_pico",
    "name": "getThings",
    "httpStatus": 500
  }
}

Implemented operations (MCP-friendly)

These helpers live in src/backend/krl-operation.js and all return the envelope above:

• Manifold pico
  • Query: manifold_getThings()
  • Event: manifold_create_thing(thingName)
  • Event: manifold_remove_thing(thingName)
  • Event: manifold_change_thing_name(thingName, changedName) (note: KRL expects changedName)
• Thing pico (safeandmine + journal ruleset)
  • Query: scanTag(tagId, domain)
  • Query: getNote(thingName, title)
  • Event: updateOwnerInfo(thingName, ownerInfo: { name,email,phone,message, shareName,shareEmail,sharePhone })
  • Event: safeandmine_newtag(thingName, tagID, domain)
  • Event: addNote(thingName, title, content)

MCP server (next step)

What MCP “tool schema” means

In MCP, a tool is described by:

• name: string identifier (e.g. manifold_getThings)
• description: short human/LLM guidance
• inputSchema: JSON Schema describing the tool’s arguments

The MCP client sends: { name: "toolName", arguments: { ... } }

This repo’s MCP server scaffolding

• Tool schemas: src/mcp/tools.js
• Server (stdio): src/mcp/server.js (registers tools and returns the uniform envelope as JSON text)

Install + run

Install dependencies (needs network):

npm install

Run the MCP server:

npm run mcp:server

Once this is running, an MCP client (like a desktop app / agent runner) can connect over stdio and call tools like manifold_getThings with { "eci": "..." }.

LLM Integration

To get the mcp-client command interface working, make sure to install the AWS SDK dependency:

npm install @aws-sdk/client-bedrock-runtime

Then to get the interface up and running:

npm run client