Onplana

Onplana MCP server

Onplanaの本番環境でのMCP展開から抽出した、オープンソースのTypeScript製Model Context Protocol構築ブロックです。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サーバーを構築するには、サーバーテンプレートを使用してください。独自のコードからOnplanaのホスト型MCPを利用するには、クライアントSDKを使用してください。

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

オープンソースにする理由

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 が付与されています。各呼び出しは呼び出し元の ID で実行され、そのユーザーの権限と組織のプランに照らして確認され、監査証跡に記録されます。

読み取り（readOnlyHint: true）

• list_projects：組織内のプロジェクトを一覧表示します。ステータスで絞り込めます。
• get_project：日付、オーナー、進捗を含む、プロジェクトの詳細を取得します。
• list_tasks：プロジェクト内、または複数のプロジェクトにまたがるタスクを一覧表示します。
• get_task：説明、担当者、日付、最近のコメントを含む、タスクの詳細を取得します。
• 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：複数のタスクに同じ変更を適用します。
• assign_task：タスクの担当者を設定します。
• move_task_to_sprint：タスクをスプリントに移動する、またはスプリントから移動します。

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

• next_task：次に利用可能なタスクを選び、1 回の呼び出しでそのタスクを確保します。先に一覧表示してから確保する方法では、その間に隙ができ、2 つのエージェントが同じタスクを取得する可能性があります。
• claim_task：特定のタスクの排他的なリースを取得します。
• renew_task_lease：作業が継続中のタスクのリースを延長します。
• release_task：リースを返却します。タスクを完了またはブロックした場合もリースは解放され、セッションを終了すると、その実行が保持しているすべてのリースが解放されます。

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

カタログには 4 つの削除ツール（タスク、プロジェクト、リスト、ドキュメント）があります。各ツールは組織ごとの切り替え設定で、組織管理者が選択を保存するまでは有効です。また、エージェントには該当する権限も必要であり、いずれのツールもアイテムを完全に破棄するのではなく、すべてごみ箱に移動します。Onplana はすべての項目の変更を監査し、履歴を保持するため、削除して作り直すよりも update_task の使用をおすすめします。

本番環境向けチェックリスト

テンプレートと SDK があればすぐに使い始められます。さらに、以下を追加してください。

• トークンごとのレート制限。 Bearer トークンごとに 1 分あたり 60～120 リクエストに制限します。 エージェントのループは人間よりもリクエストが多くなります。
• テナントごとのコスト上限。 ツールが有料 LLM を呼び出す場合は、月初からの支出に基づいてディスパッチを制御します。Onplana のデプロイでは aiMonthlyCostCapUsd を WARN / BLOCK モードで使用します。
• 監査ログ。 各ディスパッチで 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

ブラウザーでのサインインを案内し、whoami で接続を確認します。MCP サーバーは無料プランを含むすべての Onplana プランで利用できます。

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

スキル	使用する場面
onplana-project-planner	目標や概要があり、実行可能な計画を作成したい場合。プロジェクトに添付する計画書を作成し、その後、日付、依存関係、担当者、テストケースを含むタスクツリーを作成します。
onplana-autonomous-agent	計画がすでにあり、その計画を実行したい場合。タスクを引き受けて作業し、進捗と根拠を記録して、解決するか差し戻した後、次のタスクに取りかかります。

プラグインは plugins/onplana/.mcp.json でサーバーをリモート HTTP サーバーとして宣言するため、Claude Code は stdio シムを介さず直接接続します。同じ URL をすでに claude mcp add で追加している場合、Claude Code は既存のエントリーを保持してプラグイン側のエントリーをスキップするため、ツール群は引き続き 1 つだけです。

Gemini CLI にインストールする

このリポジトリにはルートに gemini-extension.json マニフェストが含まれているため、1 つのコマンドで Gemini CLI に 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：AI ネイティブなプロジェクト・ポートフォリオ管理プラットフォーム、Onplana
• Model Context Protocol specification：MCP 標準
• Anthropic prompt-injection guidance：このリポジトリのラッパーが実装するセキュリティパターン