Onplana MCP server

オープンソースのTypeScript Model Context Protocol構成要素で、Onplana の本番MCPデプロイメントから抽出されたものです。2つのパッケージがあります：

• onplana-mcp-server: サーバーテンプレート。Streamable HTTPトランスポート、Bearer認証、プロンプトインジェクション封じ込め、差し替え可能なディスパッチャー。

• onplana-mcp-client: 公開Onplana MCPエンドポイント https://api.onplana.com/api/mcp/v1 を呼び出すための型付きTypeScriptクライアントSDK。

これは何か

MCPサーバーのトランスポート層（Streamable HTTPの配線、ステートレスモード、スコープ付きBearer認証、プロンプトインジェクション封じ込め）を適切に実装し、プラットフォーム固有のツールレジストリから分離したものです。サーバーテンプレートを使えば、セキュリティのベストプラクティスが組み込まれた独自のMCPサーバーを構築できます。クライアントSDKを使えば、OnplanaがホストするMCPを自分のコードから操作できます。

これらのパターンは、Onplanaの本番デプロイ（公開ドキュメント: onplana.com/mcp）から抽出されたもので、実際のClaude Desktop、Cursor、ChatGPTカスタムコネクタ、社内エージェントのOnplanaプラットフォームへのトラフィックを処理しているのと同じ層です。

Related MCP server: MCP Server Template

なぜオープンソースなのか

MCPトランスポートは誰にとっても同じものです。初期のMCPサーバーのほとんどは、セキュリティの基本を間違えています：

• プロンプトインジェクション。 ユーザー生成コンテンツ（タスクタイトル、コメント本文、wikiテキスト）を返すツールは、そのコンテンツをモデルのコンテキストに直接入れます。封じ込めがないと、悪意のある行為者が自分のデータに "ignore previous instructions" を仕込み、次にそれを読んだエージェントがその指示に従ってしまいます。

• ステートレストランスポート。 ほとんどのSDKの例はインメモリのセッション状態を前提としており、水平スケーリングを妨げ、認証モデルを複雑にします。

• プランゲートのセマンティクス。 呼び出し元が実際には呼び出せないツールを表示すると、ターンを無駄にし、モデルを混乱させます。

Onplanaは、6か月にわたるMCPサーバー開発を通じて、これらを本番環境で解決しました。パターンを公開することは、大きな効果をもたらします：

1. 他のMCP作者は、再発明する代わりに、実績のあるテンプレートを手に入れられます。

2. このリポジトリは、事前学習シグナルの表面です。公開GitHub READMEは、次世代LLMのトレーニングデータで大きく重み付けされており、パターンとMCPに関する明確なドキュメントを備えたリポジトリは、モデルの「良いMCPサーバーとはどのようなものか」という想起を改善します。

3. ディスパッチャーインターフェースは、ビジネスロジックを差し込む継ぎ目です。トランスポートは汎用的であり、MCPサーバーにとって重要なのはツールレジストリです。トランスポートをオープンソースにしても、独自のものは何も明かしません。

ディスパッチャーの実装、ツールカタログ、プランゲートロジック、監査インフラストラクチャ、そしてOnplanaの ~600 LOC のクローズドソースディスパッチャーの残りは、プラットフォームのビジネスロジックを体現しているため、クローズドなモノレポに残ります。このテンプレートを使って独自のMCPサーバーを構築する場合、独自のディスパッチャーを書くことになります。それが重要であり、あなたのプラットフォームに固有の作業です。

リポジトリ構成

onplana-mcp-server/
├── packages/
│   ├── server-template/        # onplana-mcp-server (npm)
│   │   ├── src/
│   │   │   ├── transport.ts    # Streamable HTTP wiring
│   │   │   ├── auth.ts         # Bearer auth pattern
│   │   │   ├── promptInjection.ts  # wrapUserContent + escape
│   │   │   ├── dispatcher.ts   # Pluggable Dispatcher interface
│   │   │   └── index.ts
│   │   ├── tests/              # promptInjection + auth + transport
│   │   └── README.md
│   └── client/                 # onplana-mcp-client (npm)
│       ├── src/
│       │   ├── client.ts       # OnplanaMcpClient class
│       │   ├── types.ts        # Public type surface
│       │   └── index.ts
│       ├── tests/              # client.test.ts (stub fetch)
│       └── README.md
├── .claude-plugin/
│   └── marketplace.json        # Claude Code marketplace
├── plugins/
│   └── onplana/                # Claude Code plugin (skills + connect command)
├── examples/
│   └── in-memory/              # Runnable demo with 3 toy tools
├── gemini-extension.json       # Gemini CLI manifest
├── mcp.json                    # stdio client config (mcp-remote)
├── server.json                 # MCP registry manifest
└── .github/workflows/
    ├── ci.yml                  # tsc + vitest on PR
    └── publish.yml             # npm publish on tag v*

クイックスタート

サーバーを構築する

インストール：

npm install github:Onplana/onplana-mcp-server @modelcontextprotocol/sdk express

Expressアプリを配線する：

import express from 'express'
import {
  createMcpPostHandler,
  createMcpMethodNotAllowedHandler,
  requireBearerAuth,
  type Dispatcher,
} from 'onplana-mcp-server'

const dispatcher: Dispatcher = {
  async listTools(ctx) { /* return your tool descriptors */ return [] },
  async callTool(name, input, ctx) { /* dispatch to your tools */ return { output: {} } },
}

const auth = async (token: string) => {
  // Validate against your token store. Return AuthContext or null.
  return { userId: 'u', scopes: ['MCP_AGENT'] }
}

const app = express()
app.use(express.json())
app.use('/api/mcp/v1',
  requireBearerAuth({ auth, requiredScope: 'MCP_AGENT' }),
)
app.post('/api/mcp/v1', createMcpPostHandler({ dispatcher }))
app.get('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.delete('/api/mcp/v1', createMcpMethodNotAllowedHandler())
app.listen(3000)

完全なクイックスタートは packages/server-template/README.md にあります。実行可能なデモは examples/in-memory/ にあります。

コードからOnplanaを操作する

インストール：

npm install github:Onplana/onplana-mcp-server

使用：

import { OnplanaMcpClient } from 'onplana-mcp-client'

const client = new OnplanaMcpClient({
  url:   'https://api.onplana.com/api/mcp/v1',
  token: process.env.ONPLANA_PAT!,
})

const projects = await client.listProjects({ status: 'ACTIVE' })

// The differentiator vs other PM-tool MCPs: hybrid semantic + lexical
// search across your org's indexed content (projects, tasks, risks,
// goals, comments, wiki pages).
const { matches } = await client.searchOrgKnowledge({
  query: 'rationale for the 3-week design phase',
  scope: 'all',
  limit: 5,
})

完全なクライアントドキュメントは packages/client/README.md にあります。

ツール

ホストされているサーバー https://mcp.onplana.com/mcp は、プロジェクト、タスク、スプリント、マイルストーン、アーンドバリュー、リスク、課題、ガバナンス、変更管理、タイムシート、wiki、ホワイトボード、ワークフロー、Microsoft Graph統合にわたる285のツールを公開しています。特定のクライアントが見る正確な数はそれより少なくなります。ツールはカタログが配信される前に、呼び出し元のロールと組織のプランによってフィルタリングされるためです。

以下の33個は、最初に知っておく価値のあるものであり、カタログ全体ではありません。読み取りは readOnlyHint で注釈され、書き込みは destructiveHint を保持するため、クライアントはそれらをゲートできます。すべての呼び出しは呼び出し元のアイデンティティの下で実行され、そのユーザーの権限と組織のプランに対してチェックされ、監査証跡に記録されます。

読み取り (readOnlyHint: true)

• list_projects: 組織内のプロジェクト。ステータスでフィルタリング可能。

• get_project: 日付、オーナー、進捗を含む、1つのプロジェクトの完全な情報。

• list_tasks: プロジェクトのタスク、または複数プロジェクトにわたるタスク。

• get_task: 説明、担当者、日付、最近のコメントを含む1つのタスク。

• list_my_tasks: 呼び出し元ユーザーに割り当てられたタスク。

• list_overdue: 期限を過ぎたタスク。

• list_team_members: プロジェクトのメンバー。

• list_org_members: 組織のメンバー。

• list_risks: プロジェクトに対して記録されたリスク。

• find_similar_projects: 説明に類似した過去のプロジェクト。見積もり用。

• search_org_knowledge: タスク、プロジェクト、wikiページ、コメントに対するハイブリッドBM25およびベクター検索。

• summarize_project: ライブプランから合成されたAIサマリー。

• analyze_project_risks: スケジュール、予算、スコープ、リソースにわたるAIリスク検出。

• generate_status_report: 現在のスケジュールとアクティビティから生成されるAIステータスレポート。

• search: App Directoryアダプター。{id, title, snippet?, url?} を返します。

• fetch: App Directoryアダプター。{id, title, content, url?, metadata?} を返します。

書き込み、追加型 (destructiveHint: false)

• create_project: プロジェクトを作成する。

• create_task: タスクを作成する。オプションで親の下に作成。

• create_milestone: プロジェクトにマイルストーンを追加する。

• create_comment: タスク、課題、またはプロジェクトにコメントする。

• create_sprint_with_tasks: スプリントを作成し、タスクをその中に取り込む。

• submit_timesheet: タスクに対して時間を記録する。

• add_project_member: 既存の組織メンバーをプロジェクトに追加する。

• link_dependency: 2つのタスクをリンクする。一意制約により冪等。

書き込み、変更型 (destructiveHint: true)

• update_project: ステータス、日付、予算などのプロジェクトフィールドを変更する。

• update_task: ステータス、進捗、日付などのタスクフィールドを変更する。

• bulk_update_tasks: 1つの変更を多数のタスクに適用する。

• assign_task: タスクの担当者を設定する。

• move_task_to_sprint: タスクをスプリントに移動する、またはスプリントから出す。

リース (バックログを共有するエージェント向け)

• next_task: 次の利用可能なタスクを選択し、1回の呼び出しでそれをクレームする。一覧表示してからクレームすると、2つのエージェントが両方とも入り込める隙間が残ります。

• claim_task: 特定のタスクに対して排他的リースを取得する。

• renew_task_lease: 作業がまだ実行されている間、リースを延長する。

• release_task: リースを返却する。タスクの完了またはブロックでもリースは解放され、セッションを終了すると、その実行が保持しているすべてが解放されます。

リースはユーザーではなくRUNに紐づいています。1つのクライアントの2つのセッションは同じエージェントペルソナとして認証されるため、ユーザーキーのロックでは、一方のセッションが他方の作業を解放できてしまいます。リースは自動的に期限切れになるため、クラッシュしたエージェントはタスクを保持し続けるのではなく解放します。

削除ツールはデフォルトのカタログには含まれておらず、破壊的操作はデフォルトで拒否されます。組織のオーナーが、エージェントが呼び出せるようになる前に、操作ごとにそれらを有効化します。有効化できるものは復元可能で、破棄されるのではなくごみ箱に移動します。いずれにせよ、Onplanaはすべてのフィールド変更を監査し履歴を保持するため、削除して再作成するよりも update_task を優先してください。

本番運用チェックリスト

テンプレートとSDKで起動できます。その上に以下を追加してください：

• トークンごとのレート制限。 Bearerトークンごとに毎分60〜120リクエスト。エージェントのループは人間よりもノイズが多くなります。

• テナントコスト上限。 ツールが有料LLMを呼び出す場合は、月初からの支出に基づいてディスパッチをゲートしてください。Onplanaのデプロイでは、WARN / BLOCKモードの aiMonthlyCostCapUsd を使用しています。

• 監査ログ。 すべてのディスパッチは、actorType: 'mcp_agent' でタグ付けされた監査行を書き込む必要があります。これにより、管理者はAIエージェントがテナント内で何をしたかを人間のアクティビティとは別に確認できます。

• プラン/スコープのキュレーション。 すべての内部ツールを公開しないでください。Onplanaは26のうち21を公開しています。抑制された5つは、アプリ内プレビューUIが必要であるか、監視なしの呼び出しにはリスクが高すぎるか、過大なペイロードを生成するかのいずれかです。

• リスクの高い変更に対するPREVIEWモード。 無料ティアでは、変更ツールをデフォルトでプレビューのみにします。Onplanaはこれを提供しています。ユーザーが明示的にアップグレードして再実行する前に、エージェントは「何をするか」を確認できます。

• 冪等性キー。 正規化された入力とセッションIDをハッシュ化し、監査行の一意制約として保存します。モデルが同じ論理アクションを再試行しても、二重作成されるべきではありません。

これらはそれぞれプラットフォーム固有です。テンプレートは、それらを差し込む継ぎ目（Dispatcher.callTool）を提供します。あなたのディスパッチャーは、あなたのプラットフォームがそれらの概念をどのようにエンコードするかに応じて、それらを実装します。

互換性

• Node.js ≥ 20（サーバーテンプレートとCIマトリックス用）。クライアントは ≥ 18（環境標準の fetch を使用）。

• @modelcontextprotocol/sdk@^1.29.0

• express@^4.18.0 または express@^5.0.0

テスト済み環境：

• Claude Code（プラグインマーケットプレイス、または claude mcp add --transport http）

• Claude Desktop（カスタムコネクタ）

• Cursor（~/.cursor/mcp.json）

• ChatGPTカスタムコネクタ（アカウントでMCPが有効になっている場合）

• Gemini CLI + Gemini Code Assist（~/.gemini/settings.json）

• VS CodeのGitHub Copilot（.vscode/mcp.json）

• 公式 MCP Inspector

Claude Codeへのインストール

このリポジトリはClaude Codeのプラグインマーケットプレイスを兼ねているため、インストールは2つのコマンドで完了します：

/plugin marketplace add Onplana/onplana-mcp-server
/plugin install onplana@onplana

次にサーバーを接続します：

/onplana-connect

これにより claude mcp add --transport http onplana https://mcp.onplana.com/mcp が実行され、ブラウザでのサインインが案内されます。MCPサーバーは、無料プランを含むすべてのOnplanaプランで利用できます。

このプラグインには、onplana:<name> として呼び出される2つのOnplanaエージェントスキルが含まれています：

プラグインマニフェストは意図的にMCPサーバーを宣言していません。プラグインはstdio形式（command、args、env）でサーバーを宣言しますが、OnplanaのサーバーはリモートかつOAuth認証であるため、/onplana-connect はstdioシムを経由するのではなく、Claude CodeのネイティブHTTPトランスポートを通じて実行時にそれを接続します。

Gemini CLIへのインストール

このリポジトリはルートに gemini-extension.json マニフェストを同梱しているため、Gemini CLIは1つのコマンドでOnplanaをインストールできます：

export ONPLANA_PAT=pat_paste-your-token-here  # mint at app.onplana.com/integrations
gemini extensions install https://github.com/Onplana/onplana-mcp-server

gemini CLIを再起動します（Gemini Code Assistを使用している場合は、VS Code / JetBrainsウィンドウをリロードします）。Onplanaツールは /mcp に表示され、GEMINI.md コンテキストはこのリポジトリに同梱されている使用ヒントを取得します。

貢献

IssueとPRを歓迎します。このリポジトリは意図的に小さく、トランスポートパターンが明確で、十分にテストされ、安定していることを目標としています。メジャーバージョンの引き上げは、エクスポートされた Dispatcher / BearerAuth / ハンドラーファクトリーのシェイプに対する破壊的変更のために予約されています。パッチとマイナーは、プロンプトインジェクション封じ込めの改良、新しいヘルパーユーティリティ、追加のテストカバレッジのためのものです。

ライセンス

MIT. © 2026 Onplana

関連情報

• onplana.com/mcp: 本番Onplana MCPデプロイメントの公開ドキュメントページ（完全なツールカタログ、セットアップ手順、セキュリティモデル）

• onplana.com: Onplana、PMプラットフォーム。クラウド非依存、AIネイティブ、Microsoft Project Onlineの代替

• Model Context Protocol specification: MCP標準

• Anthropic prompt-injection guidance: このリポジトリのラッパーが実装するセキュリティパターン