@manifesto-ai/mcp

@manifesto-ai/mcp connects Manifesto domains to MCP servers and exposes Manifesto runtimes back out as MCP servers.

It ships three public surfaces:

• @manifesto-ai/mcp: mcpEffects(manifest, env?) for turning an MCP manifest into Manifesto effect handlers
• @manifesto-ai/mcp/runtime: createManifestoMcpServer(instance, options?) for serving a Manifesto runtime over MCP
• @manifesto-ai/mcp/validation: shared manifest, domain, and registry validation helpers for CLI and tooling

Install

pnpm add @manifesto-ai/mcp

mcpEffects()

Use mcpEffects() when your MEL domain declares custom effects that should call MCP tools.

import { readFileSync } from "node:fs";
import { createManifesto } from "@manifesto-ai/sdk";
import { mcpEffects } from "@manifesto-ai/mcp";

const mel = readFileSync("./manifesto/domains/trading-agent/domain.mel", "utf8");
const manifest = JSON.parse(
  readFileSync("./manifesto/domains/trading-agent/mcp-manifest.json", "utf8"),
);

const runtime = createManifesto(mel, mcpEffects(manifest)).activate();

mcpEffects() is synchronous and lazy. It does not connect to MCP servers until the first matching effect fires. Built-in effect namespaces such as array.*, record.*, and system.* are ignored.

Example manifest:

{
  "bindings": {
    "exchange.ticker": {
      "server": "market-data",
      "tool": "get_tickers",
      "paramsMap": {
        "symbols": "symbols"
      },
      "resultPath": "data"
    }
  },
  "servers": {
    "market-data": {
      "url": "https://mcp.example.com",
      "transport": "http",
      "auth": {
        "type": "env",
        "envKey": "MARKET_DATA_MCP_TOKEN"
      }
    }
  },
  "env": {
    "MARKET_DATA_MCP_TOKEN": {
      "required": true,
      "description": "Bearer token for the market data MCP server"
    }
  }
}

On failure, handlers never throw business errors back into Manifesto. They emit $error values into fail or into, and also record the same payload under $host.mcpErrors.<effectType>.

Runtime Server

Use createManifestoMcpServer() when you want to expose a Manifesto runtime as an MCP tool server.

import { createManifestoMcpServer } from "@manifesto-ai/mcp/runtime";

const server = createManifestoMcpServer(runtime, {
  transport: "http",
  port: 3000,
  auth: {
    type: "env",
    envKey: "MANIFESTO_MCP_TOKEN"
  }
});

await server.listen();

Supported transports:

• stdio
• http

HTTP auth modes:

• bearer token
• env-backed bearer token
• explicit unsafe no-auth mode for local/dev use only

Base runtimes expose:

• dispatch
• get_snapshot
• get_available_actions
• get_schema_graph
• simulate

Lineage runtimes expose:

• commit
• get_snapshot
• get_available_actions
• get_schema_graph
• simulate
• get_history
• get_world_snapshot
• get_latest_head
• restore

Validation Helpers

@manifesto-ai/mcp/validation is intended for CLI and registry tooling.

import {
  getManifestBindingCoverage,
  validateDomainFiles,
  validateMcpEffectManifest,
  validateRegistryItem,
} from "@manifesto-ai/mcp/validation";

Available helpers include:

• validateMcpEffectManifest()
• validateEnvSpecsRecord()
• getManifestBindingCoverage()
• validateDomainFiles()
• validateRegistryItem()
• validateRegistryIndex()
• partitionRegistryPeers()
• normalizeRegistryFilePath()

Development

pnpm install
pnpm run check
pnpm run test
pnpm run build

Release

This repository includes GitHub Actions support for npm publishing.

• Push to main: validates the package and attempts an automatic publish
• workflow_dispatch: supports manual publishes with npm_tag and dry_run
• Existing npm versions are skipped automatically
• The workflow supports either npm trusted publishing via GitHub OIDC or a fallback NPM_TOKEN secret

Package Exports

• @manifesto-ai/mcp
• @manifesto-ai/mcp/runtime
• @manifesto-ai/mcp/validation

License

ISC