open-index/open-npm huggingface dataset:
npm package: @mallocbaal/mcp-agent-framework-ts
Description: TypeScript MCP agent framework with schema-safe message contents
Latest version: 0.5.0

# mcp-agent-framework-ts

TypeScript framework library for MCP-style agent event processing with typed response 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 optional typed `contents` (for action-only responses).
- Separate JSON-RPC endpoints for `init`, `continue`, `action`, `end`.

## Install

```bash
npm install
```

## Build

```bash
npm run build
```

## Quick start

```ts
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)

```ts
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
```

## Required bot initialization

`createApp` requires `botInitialization`. Framework checks bot existence via `checkBot` and registers it via `registerBot` if needed before first event handling.

```ts
const app = createApp({
  pipeline,
  botInitialization: {
    communicator, // must implement checkBot/registerBot
    bot: {
      key: "alura",
      name: "Alura",
      eventStream: "cli.flow.alura",
      streamingEnabled: true
    }
  }
});
```

## Tests

```bash
npm test
```