mcp-agent-framework-ts

TypeScript framework library for MCP-style agent event processing with strict contents contract:

contents: [MessageContentItemInput!]!

Features

• Event model compatible with CLI_FLOW_INIT | CLI_FLOW_CONTINUE | CLI_FLOW_ACTION | CLI_FLOW_END.
• Typed builders for all MessageContentDataInput variants:
  • TEXT, ACTIVITY, MS_ITEM, LDC, CALL_INVITE, TICKET
  • SELECTOR, FILE, IMAGE, CARDS, IMAGE_INPUT, POLICY
• Pipeline API that returns framework result with typed contents.
• Separate JSON-RPC endpoints for init, continue, action, end.

Install

npm install

Build

npm run build

Quick start

import {
  Pipeline,
  textContent,
  type CliFlowEvent
} from "mcp-agent-framework-ts";

const pipeline = new Pipeline(
  {
    async processInit(_ctx, _event) {
      return {
        contents: [textContent(0, { text: "Welcome!" })]
      };
    },
    async processContinue(_ctx, event) {
      return {
        contents: [textContent(0, { text: `You said: ${event.message ?? ""}` })],
        action: { type: "AI_RESPONDING_DONE" }
      };
    },
    async processAction(_ctx, event) {
      return {
        contents: [textContent(0, { text: `Action received: ${event.actionType}` })]
      };
    }
  },
  {}
);

const messageEvent: CliFlowEvent = {
  eventType: "CLI_FLOW_CONTINUE",
  eventId: "evt-1",
  flowId: "flow-1",
  chatId: "chat-1",
  participantId: "participant-1",
  accountId: "account-1",
  message: "hello"
};

await pipeline.handle(undefined, messageEvent);

const actionEvent: CliFlowEvent = {
  eventType: "CLI_FLOW_ACTION",
  eventId: "evt-2",
  flowId: "flow-1",
  chatId: "chat-1",
  participantId: "participant-1",
  accountId: "account-1",
  actionType: "PING",
  actionData: { source: "ui" }
};

await pipeline.handle(undefined, actionEvent);

pipeline.handle(...) returns { contents, metadata?, action? } and JSON-RPC endpoints return this as result.

JSON-RPC endpoints (separate per flow type)

import { createJsonRpcEndpoints } from "mcp-agent-framework-ts";

const endpoints = createJsonRpcEndpoints(app);

// Four separate handlers/endpoints:
// POST /jsonrpc/init      -> endpoints.init
// POST /jsonrpc/continue  -> endpoints.continue
// POST /jsonrpc/action    -> endpoints.action
// POST /jsonrpc/end       -> endpoints.end

Tests

npm test