1. AI連携デモ用
  2. 開発仕様書
  3. MCPサーバー処理フロー仕様書
開発仕様書/

MCPサーバー処理フロー仕様書

概要

このドキュメントは、RunbookのMCP（Model Context Protocol）サーバーの処理フローを詳細に説明した仕様書です。コードベースの分析結果を基に、システムの全体的な動作を理解しやすい形で図解しています。

処理フロー図

MCPサーバー処理フロー図

システム構成

1. 主要コンポーネント

MCPクライアント

  • Claude Codeやその他のMCPクライアントからのリクエストを受信
  • 標準的なMCPプロトコルを使用して通信

MCPサーバー

  • リクエストを受信し、適切なハンドラーに振り分け
  • ツールとリソースの管理を行う中央制御部

Runbook API

  • GraphQLベースの外部API
  • 記事、ブック、ワークフロー管理機能を提供

2. サーバー内部構成

ツール (Tools) MCPサーバーは以下のツールを提供します：

  • search-articles: キーワードによる記事検索
  • get-article: 記事IDによる記事取得
  • list-articles: ブック内の記事一覧取得
  • create-article: 新規記事作成
  • update-article: 記事内容更新
  • list-books: ブック一覧取得
  • list-categories: カテゴリー一覧取得
  • get-process: ワークフロー状態取得
  • run-process: ワークフロー実行
  • finish-process: ワークフロー完了

リソース (Resources) MCPサーバーは以下のリソースパターンをサポートします：

  • runbook://books/{bookUid}: ブック情報
  • runbook://articles/{articleUid}: 記事情報
  • runbook://workspaces/{workspaceUid}: ワークスペース情報

GraphQLクエリ バックエンドAPIとの通信には以下のクエリを使用します：

  • getArticleQuery: 記事データ取得
  • createArticleQuery: 記事作成
  • updateArticleQuery: 記事更新
  • getBookQuery: ブック情報取得
  • getBookWithRunStatesQuery: ランステート付きブック取得
  • getBookWithRunStateQuery: 特定ランステート付きブック取得
  • getArticleWithPropertiesQuery: プロパティ付き記事取得
  • runProcessQuery: プロセス実行
  • updateRunStateQuery: ランステート更新
  • finishProcessQuery: プロセス完了

処理フロー

基本的な処理フロー

  1. リクエスト受信
  • MCPクライアントからツール呼び出しまたはリソース取得のリクエストを受信
  • サーバーがリクエストタイプを判別
  1. ハンドラ実行
  • 適切なハンドラーを選択
  • 入力パラメータの検証
  • 必要なデータの前処理
  1. GraphQL実行
  • 対応するGraphQLクエリを構築
  • Runbook APIとの通信実行
  • レスポンスデータの取得
  1. レスポンス処理
  • 取得したデータの変換・整形
  • MCPクライアントへの結果返却

ワークフロー処理フロー

ワークフローの処理は以下のステップで行われます：

  1. 初期化: 新しいワークフローの開始
  2. 実行: 各ステップの処理実行
  3. 次のステップ: 次のステップへの遷移
  4. 完了: ワークフローの完了処理

技術仕様

アーキテクチャ特徴

  • モジュラー設計: ツール、リソース、クエリが独立したモジュールとして実装
  • 動的登録: ツールハンドラーはオブジェクトとして定義され、動的に登録される
  • 型安全性: TypeScriptによる厳密な型定義
  • 設定管理: 複数の設定ソースをサポート（CLI引数、環境変数、設定ファイル）

主要ファイル

  • src/server.ts: MCPサーバーのメインエントリーポイント
  • src/tools/tools.ts: 全ツールの実装
  • src/resources/resources.ts: リソースハンドラーの実装
  • src/queries/: GraphQLクエリ定義
  • src/types.ts: TypeScript型定義

通信プロトコル

  • MCP: Model Context Protocolによるクライアント通信
  • GraphQL: Runbook APIとの通信
  • JSON: データ交換形式

まとめ

この仕様書では、MCPサーバーの包括的な処理フローを図解と共に説明しました。システムの各コンポーネントがどのように連携し、リクエストがどのような流れで処理されるかを理解いただけたと思います。

この仕様書を参考に、MCPサーバーの動作原理を把握し、必要に応じて拡張や修正を行うことができます。

最終更新:
AI連携デモ用
開発仕様書