Pipeline Engine TypeScript SDK

Node.js / Electron アプリから Pipeline Engine の HTTP API を扱うための軽量クライアントです。現状は以下をサポートしています。

• ジョブの作成・取得・キャンセル・リラン
• Chunk 付きストリーミング (provider_chunk / item_completed / stream_finished を逐次取得)

インストール

npm install @pipeforge/sdk

※この SDK は Node.js 18 以降（組み込みの fetch / WHATWG Streams 利用）を前提にしています。Electron ではメインプロセスで利用するか、レンダラから fetch を注入してください。

使い方

import { PipelineEngineClient, JobRequest } from "@pipeforge/sdk";

const client = new PipelineEngineClient({ baseUrl: "http://127.0.0.1:8085" });

const jobReq: JobRequest = {
  pipeline_type: "openai.funmarkdown.v1",
  input: {
    sources: [{ kind: "note", content: "雑学を話して" }]
  }
};

const { job, events } = await client.streamJobs(jobReq);
console.log("job accepted", job.id);

for await (const evt of events) {
  switch (evt.event) {
    case "provider_chunk":
      console.log("chunk", evt.data.content);
      break;
    case "item_completed":
      console.log("step completed", evt.data.step_id);
      break;
    case "stream_finished":
      console.log("done");
      break;
  }
}

グローバル設定（Provider Profile）の更新

await client.upsertProviderProfile({
  id: "openai-cli",
  kind: "openai",
  api_key: process.env.OPENAI_API_KEY,
  base_uri: "https://api.openai.com/v1",
  default_model: "gpt-4o-mini"
});

await client.updateEngineConfig({ log_level: "debug" });

`client.streamJobs()` は `AsyncIterable<StreamingEvent>` を返すので、Electron では chunk が到着するたびに UI を更新できます。

### ジョブストリームの再開 (`after_seq`)

`streamJobByID(jobID, afterSeq)` を使うと途中で切れたストリームを `seq` 番号から再開できます。最後に受け取った `StreamingEvent.seq` を記録し、次回リクエストで `afterSeq` に渡してください。

```ts
let resumeSeq = 0;

async function consume(jobID: string) {
  const stream = await client.streamJobByID(jobID, resumeSeq);
  for await (const evt of stream) {
    resumeSeq = evt.seq ?? resumeSeq;
    renderEvent(evt);
  }
}

after_seq がサーバー側の履歴とずれた場合は、フルストリーム（after_seq=0）で取り直してください。詳しい仕様は docs/mcp/StreamingResume.md を参照してください。

MCP Adapter CLI (pipeline-engine-mcp)

@pipeforge/sdk には MCP (Model Context Protocol) アダプタ CLI が同梱されています。Node.js 18+ 環境で npm install -g @pipeforge/sdk を実行すると pipeline-engine-mcp コマンドが利用できます。

npm install -g @pipeforge/sdk
PIPELINE_ENGINE_ADDR="http://127.0.0.1:8085" pipeline-engine-mcp

manifest 例（Claude Desktop / Cursor 用）:

{
  "name": "pipeforge",
  "description": "Pipeline Engine MCP adapter",
  "commands": [
    {
      "command": "pipeline-engine-mcp",
      "env": {
        "PIPELINE_ENGINE_ADDR": "http://127.0.0.1:8085",
        "PIPELINE_ENGINE_OPENAI_API_KEY": "${PIPELINE_ENGINE_OPENAI_API_KEY}"
      }
    }
  ],
  "tools": [
    { "name": "startPipeline", "description": "Create job via /v1/jobs" },
    { "name": "streamJob", "description": "Forward NDJSON events" },
    { "name": "getJob", "description": "Fetch job result" },
    { "name": "cancelJob", "description": "Cancel running job" },
    { "name": "rerunJob", "description": "Rerun job from step" },
    { "name": "upsertProviderProfile", "description": "Update provider profile" }
  ]
}

streamJob / startPipeline(stream=true) では tool_event が逐次送信されます。params.kind（status/chunk/result/error）と params.seq を利用すると、クライアント側でトークン描画や欠落検知が容易になります。manifest の詳細や MCP ホストへの登録手順は docs/mcp/ManifestGuide.md を参照してください。

ビルド

npm install
npm run build

dist/ に ESM + 型定義が出力されます。必要に応じて npm publish の前に package.json の name や version を調整してください。