Sample MCP Server

SQL データベース統合を備えた MCP サーバー

これは、TypeScript と Express.js で構築された Model Context Protocol（MCP）サーバーです。SQL データベース、Jira API、データ処理および分析のためのインテリジェントな AI 搭載ツールを包括的に統合します。このサーバーはリアルタイム通信に Server-Sent Events（SSE）を使用し、ユーザー体験を向上させる永続ストレージを備えています。

主な機能

🗄️ SQL データベース統合

• ユーザー、ベンダー、商品、通貨、ロールに対する完全な CRUD 操作
• 高度な検索機能とページネーション機能
• SQL Server との堅牢な接続管理
• データベースのヘルスモニタリングと接続テスト

🎯 Jira 統合

• JQL（Jira Query Language）をサポートする包括的な Jira API 統合
• AI を使用したインテリジェントな JQL クエリ生成
• 類似性に基づく重複排除機能を備えた JQL の例の永続ストレージ
• 課題の作成、検索、管理
• スプリントとプロジェクトの分析

🤖 AI 搭載機能

• インテリジェントなツールルーティングとデータ処理のための OpenAI 統合
• ユーザー体験を向上させるリアルタイムのストリーミング応答
• 学習機能を備えたスマートな JQL クエリ生成
• コンテキストに応じたデータ分析と Markdown 形式への整形

📊 データ管理

• DummyJSON API からの商品データの統合
• DummyJSON API からのユーザーデータの統合
• リアルタイムのアプリケーションステータスモニタリング
• ファイルの自動同期機能を備えた永続ストレージ

🔄 リアルタイム通信

• 応答のストリーミングに Server-Sent Events（SSE）を使用
• 複数の同時セッションの管理
• 適切なエラー処理と接続管理

利用可能なツール

🗄️ SQL データベースツール

ユーザー管理

• get-users - ページネーションを指定してユーザーの一覧を取得
• get-user-by-id - ID を指定して特定のユーザーの詳細情報を取得
• search-users - キーワードでユーザーを検索

ベンダー管理

• get-vendors - ページネーションを指定してベンダーの一覧を取得
• get-vendor-by-id - ID を指定して特定のベンダーの詳細情報を取得
• search-vendors - キーワードでベンダーを検索

商品管理

• get-commodities - ページネーションを指定して商品の一覧を取得
• get-commodity-by-id - ID を指定して特定の商品の詳細情報を取得
• search-commodities - キーワードで商品を検索

通貨管理

• get-currencies - ページネーションを指定して通貨の一覧を取得
• get-currency-by-id - ID を指定して特定の通貨の詳細情報を取得
• search-currencies - キーワードで通貨を検索

ロール管理

• get-roles - ページネーションを指定してロールの一覧を取得
• get-role-by-id - ID を指定して特定のロールの詳細情報を取得
• search-roles - キーワードでロールを検索

🎯 Jira 統合ツール

• get-jira-issue-by-id - 特定の Jira 課題の詳細情報を取得
• search-jira-issues - インテリジェントな JQL 生成を使用して Jira 課題を検索
• create-jira-issue - 指定したプロジェクト、概要、課題タイプで新しい Jira 課題を作成
• create-jira-subtask - 既存の Jira 課題の下にサブタスクを作成

📊 商品・外部 API ツール

• get-products - DummyJSON API からページネーションを指定して商品一覧を取得
• get-product-by-id - ID を指定して特定の商品の詳細情報を取得
• search-products - キーワードで商品を検索
• get-products-by-category - 特定のカテゴリーに属するすべての商品を取得
• get-categories - すべての商品カテゴリーの一覧を取得

🔍 アプリケーションモニタリング

• get-application-status - 異なる環境における特定のアプリケーションのリアルタイムステータス情報を取得

🗄️ SQL データベース統合

この MCP サーバーには、エンタープライズグレードのデータ管理を実現する包括的な SQL Server 統合が含まれています。

データベースのセットアップ

1. SQL Serverをインストールして構成する

   • SQL Serverがインストールされ、実行中であることを確認します
   • 対象のデータベースを作成します

2. データベース接続を構成する

   データベースの認証情報を含む .env ファイルをプロジェクトのルートに作成します：

   # SQL Server Configuration
   MSSQL_USER=your_username
   MSSQL_PASSWORD=your_password
   MSSQL_HOST=your_server_host
   MSSQL_DATABASE=your_database_name
   
   # Alternative: Connection String
   MSSQL_CONNECTION_STRING=Server=yourserver;Database=yourdatabase;User Id=username;Password=password;Encrypt=false;TrustServerCertificate=true;
   
   # OpenAI Configuration (Required for AI features)
   OPENAI_API_KEY=your_openai_api_key
   LLM_MODEL=gpt-4
   
   # Jira Configuration (Optional)
   JIRA_URL=https://your-domain.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your_jira_api_token
   

3. データベーススキーマ

   サーバーは、SQLデータベースに次のテーブルがあることを前提としています：

   • Users - ロールと認証情報を含むユーザー管理
   • Vendors - ベンダー／サプライヤー情報
   • Commodities - 商品データ
   • Currencies - 通貨情報
   • Roles - ユーザーロールの定義

データベース接続のテスト

データベースのセットアップを確認します：

npm run build
npm run test-connection

🎯 Jiraとの連携

Jira連携のセットアップ

1. Jira APIトークンを作成する

   • https://id.atlassian.com/manage-profile/security/api-tokens にアクセスします
   • 新しいAPIトークンを作成します
   • .env ファイルに追加します

2. Jiraの設定を構成する

   JIRA_URL=https://your-domain.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your_jira_api_token
   

インテリジェントなJQL機能

サーバーには、高度なJQL（Jira Query Language）機能が含まれています：

• AIを活用したJQL生成：自然言語のクエリをJQLに変換します
• 継続的な学習：成功したJQLの例を保存し、今後のクエリを改善します
• スマートな重複排除：類似性の検出により、JQLの重複例を防ぎます
• リアルタイム同期：JQLの例は data/jql-examples.json にすぐに保存されます

JQLクエリの例

システムは使用状況から学習し、次のようなクエリに対するJQLを生成できます：

• 「現在のスプリントで未解決のバグを表示」
• 「John Doeに割り当てられたすべてのタスクを取得」
• 「今週作成された優先度の高い課題を検索」
• 「ベロシティ分析用に、完了したすべてのスプリントを表示」

🤖 AI連携

OpenAIの構成

サーバーは、インテリジェントなデータ処理とクエリ生成にOpenAIを使用します：

1. OpenAI APIキーを取得する

   • https://platform.openai.com/api-keys にアクセスします
   • 新しいシークレットキーを作成します
   • .env ファイルに追加します

2. 対応モデル

   • GPT-4（推奨）
   • GPT-3.5-turbo
   • OpenAI互換モデル

AI機能

• インテリジェントなツールルーティング：ユーザーのクエリに基づいて、使用するツールを自動的に判断します
• リアルタイムストリーミング：ユーザー体験を向上させるため、応答をリアルタイムでストリーミングします
• コンテキストを考慮した処理：複数回のやり取りを通じてコンテキストを維持します
• データのフォーマット：応答をMarkdownの表、グラフ、またはテキストとして自動的にフォーマットします

🚀 インストールとセットアップ

前提条件

• Node.js（v16以降）
• npmまたはyarn
• SQL Server（データベース機能用）
• OpenAI APIキー（AI機能用）
• Jiraアカウント（任意、Jira連携用）

インストール手順

1. リポジトリをクローンする

   git clone <repository-url>
   cd MCP-SERVER
   

2. 依存関係をインストールする

   npm install
   

3. 環境を構成する

   サンプル環境ファイルをコピーして、設定を構成します：

   copy .env.example .env
   

   .env を編集し、固有の設定を行います（上記のセットアップセクションを参照）。

4. プロジェクトをビルドする

   npm run build
   

5. サーバーを起動する

   npm run start
   

開発モード

自動再コンパイルとホットリロードを有効にして開発する場合：

npm run dev

🔧 VS Codeとの連携

使用可能なタスク

このプロジェクトには、開発を簡単にするVS Codeタスクが含まれています：

1. Ctrl+Shift+Pを押し、「Tasks: Run Task」を選択します
2. 使用可能なタスクから選択します：
   • MCPサーバーをビルド：TypeScriptコードをコンパイルします
   • MCPサーバーを起動：サーバーをビルドして起動します
   • 開発用MCPサーバー（監視モード）：自動リロードを有効にした開発モード

デバッグ

VS CodeでMCPサーバーをデバッグします：

1. F5を押すか、「Run > Start Debugging」を選択します
2. 「Launch MCP Server」構成を選択します
3. Debug Consoleでデバッグ出力を確認します

AIアシスタントでの使用

1. 上記のタスクを使用してMCPサーバーを起動します
2. AIアシスタント（GitHub Copilotなど）をサーバーに接続します
3. 自然言語でデータの要求や操作を行います

📁 プロジェクト構成

🏗️ アーキテクチャの概要

graph TD
    A[🎯 MCP Server] --> B[🎮 Controllers Layer]
    A --> C[🏢 Services Layer]
    A --> D[📋 Models Layer]
    A --> E[⚙️ Configuration Layer]
    
    B --> B1[👥 User Controller]
    B --> B2[🎫 Jira Controller]
    B --> B3[📦 Product Controller]
    B --> B4[🏪 Vendor Controller]
    B --> B5[📊 Commodity Controller]
    B --> B6[💰 Currency Controller]
    B --> B7[🔐 Role Controller]
    
    C --> C1[🗄️ SQL Services]
    C --> C2[🎫 Jira Service]
    C --> C3[📦 Product Service]
    C --> C4[👥 User Service]
    
    C1 --> C1A[SQL User Service]
    C1 --> C1B[SQL Vendor Service]
    C1 --> C1C[SQL Commodity Service]
    C1 --> C1D[SQL Currency Service]
    C1 --> C1E[SQL Role Service]
    
    D --> D1[🗃️ Database Models]
    D --> D2[🌐 API Models]
    D --> D3[📝 Type Definitions]
    
    E --> E1[💾 Database Config]
    E --> E2[🌐 API Config]
    E --> E3[🗄️ MSSQL Config]
    
    F[🌍 External Systems] --> F1[🗄️ SQL Server Database]
    F --> F2[🎫 Jira API]
    F --> F3[📦 DummyJSON API]
    F --> F4[🤖 OpenAI API]
    
    G[💾 Data Storage] --> G1[📄 JQL Examples JSON]
    G --> G2[📊 Application Data]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#e0f2f1
    style G fill:#f1f8e9

🔄 データフローアーキテクチャ

sequenceDiagram
    participant 👤 Client
    participant 🌐 SSE Transport
    participant 🤖 AI Router
    participant 🎮 Controller
    participant 🏢 Service
    participant 🗄️ Database
    participant 🧠 OpenAI
    
    👤->>🌐: 📝 Natural Language Request
    🌐->>🤖: 🔀 Route Message
    🤖->>🧠: 🔍 Analyze Intent
    🧠-->>🤖: 🎯 Tool Selection
    🤖->>🎮: ⚡ Execute Tool
    🎮->>🏢: 🛠️ Business Logic
    🏢->>🗄️: 📊 Data Query
    🗄️-->>🏢: 📈 Raw Data
    🏢-->>🎮: 🔧 Processed Data
    🎮->>🧠: 📋 Format Request
    🧠-->>🎮: 📄 Formatted Response
    🎮-->>🌐: 🌊 Stream Response
    🌐-->>👤: ⚡ Real-time Output

📂 詳細なファイル構成

MCP-SERVER/
├── 📁 data/                          # 💾 Persistent Data Storage
│   └── 📄 ...                        # 📄 Configuration files
│
├── 📁 src/                           # 💻 Source Code
│   ├── 📄 ...                        # 📄 TypeScript files
│   │
│   ├── 📁 app-data/                  # 📊 Application Data
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 config/                    # ⚙️ Configuration Files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 controllers/               # 🎮 MCP Tool Controllers
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 db-models/                 # 🗃️ Database Models
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 llm-api/                   # 🤖 AI Integration
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 models/                    # 📋 Data Models
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 modules/                   # 🔧 Core Server Modules
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 services/                  # 🏢 Business Logic Services
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   ├── 📁 types/                     # 📝 TypeScript Definitions
│   │   ├── 📄 ...                    # 📄 TypeScript files
│   │   └── 📄 ...                    # 📄 TypeScript files
│   │
│   └── 📁 utils/                     # 🛠️ Utility Functions
│       └── 📄 ...                    # 📄 TypeScript files
│
├── 📁 scripts/                       # 🔨 Build & Deployment
│   └── 📄 ...                        # 📄 JavaScript files
│
├── 📄 ...                            # 📄 HTML files
├── 📄 ...                            # 📄 Configuration files
├── 📄 ...                            # 📄 Configuration files
├── 📄 ...                            # 📄 Configuration files
└── 📄 ...                            # 📄 Documentation files

🔀 コンポーネントの相互作用マップ

graph LR
    subgraph "🌍 External APIs"
        EXT1[🗄️ SQL Server]
        EXT2[🎫 Jira API]
        EXT3[📦 DummyJSON]
        EXT4[🤖 OpenAI]
    end
    
    subgraph "🎯 MCP Server Core"
        SSE[🌐 SSE Transport]
        ROUTE[🤖 AI Router]
        CTRL[🎮 Controllers]
        SVC[🏢 Services]
    end
    
    subgraph "💾 Data Layer"
        DB[(🗄️ Database)]
        FILES[📄 JSON Files]
    end
    
    CLIENT[👤 Client] --> SSE
    SSE --> ROUTE
    ROUTE --> CTRL
    CTRL --> SVC
    
    SVC --> EXT1
    SVC --> EXT2
    SVC --> EXT3
    SVC --> EXT4
    
    SVC --> DB
    SVC --> FILES
    
    style CLIENT fill:#e3f2fd
    style SSE fill:#f1f8e9
    style ROUTE fill:#fff3e0
    style CTRL fill:#fce4ec
    style SVC fill:#e8f5e8
    style DB fill:#e0f2f1
    style FILES fill:#f3e5f5

🔍 API リファレンスとデータソース

外部 API

• DummyJSON Products：https://dummyjson.com/products
• DummyJSON Users：https://dummyjson.com/users
• Jira REST API：Atlassian Cloud／Server REST API v2／v3
• OpenAI API：インテリジェントな処理に使用する GPT モデル

レスポンス形式

サーバーは複数のレスポンス形式に対応しています。

• Markdown テーブル：テーブル形式の構造化データ
• Markdown テキスト：分析を含む整形済みテキスト
• チャート：チャートライブラリを使用したデータの可視化
• JSON：生の構造化データ

🚦 サーバー通信

Server-Sent Events（SSE）

サーバーはリアルタイム通信に SSE を使用します。

• エンドポイント：/sse/stream
• メッセージエンドポイント：/messages
• セッション管理：ID を使った自動セッション処理
• ストリーミングレスポンス：UX を向上させるリアルタイムのデータストリーミング

CORS 設定

サーバーは、適切な CORS ヘッダーを使用してクロスオリジンリクエストを処理できるように設定されています。

💡 使用例

基本的なクエリ

# Get all users with pagination
curl "http://localhost:3000/messages" -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "show me all users"}'

# Search for specific vendor
curl "http://localhost:3000/messages" -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "find vendor with name containing Microsoft"}'

# Get Jira issues
curl "http://localhost:3000/messages" -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "show me open bugs in current sprint"}'

自然言語クエリ

AI を活用したサーバーは自然言語を理解します。

• 「John に割り当てられた優先度の高いバグをすべて表示して」
• 「今月作成されたベンダーのうち、最新の 10 件を取得して」
• 「USD 通貨の取引をすべて検索して」
• 「完了したスプリントのベロシティチャートを表示して」
• 「管理者ロールを持つユーザーをすべて一覧表示して」

JQL の学習例

サーバーは JQL の使用状況から学習します。

User Query: "show me open bugs"
Generated JQL: project = SCRUM AND issuetype = Bug AND status != "Done" ORDER BY priority DESC
Saved: ✅ (New example learned)

User Query: "get open bugs"  
Generated JQL: project = SCRUM AND issuetype = Bug AND status != "Done" ORDER BY priority DESC
Saved: ❌ (Duplicate detected - 85% similarity)

🛠️ カスタマイズ

新しいツールの追加

1. コントローラーを作成

   // src/controllers/myController.ts
   export function registerMyTools(server: McpServer) {
     server.tool('my-tool', 'Description', schema, handler);
   }
   

2. メインに登録

   // src/index.ts
   import { registerMyTools } from './controllers/myController.js';
   registerMyTools(server);
   

データベースモデルの拡張

1. インターフェースを追加

   // src/db-models/myModel.ts
   export interface MyModel {
     Id: number;
     Name: string;
     // ... other fields
   }
   

2. サービスを作成

   // src/services/myService.ts
   export class MyService {
     async getAll(): Promise<MyModel[]> {
       // Implementation
     }
   }
   

AI プロンプトのカスタマイズ

src/llm-api/prompts.ts のプロンプトを編集します。

export const MyCustomPrompt = `
Your custom system prompt here...
Format responses as markdown tables.
`;

🐛 トラブルシューティング

よくある問題

1. データベース接続に失敗する

   • SQL Server が起動していることを確認します
   • .env ファイルの認証情報を確認します
   • npm run test-connection でテストします

2. OpenAI API エラー

   • API キーが有効であることを確認します
   • モデルが利用可能か確認します
   • API の使用制限を確認します

3. Jira 認証に失敗する

   • API トークンが正しいことを確認します
   • Jira の URL 形式を確認します
   • ユーザーの権限を確認します

4. ポートがすでに使用されている

   • 設定でポートを変更します
   • 実行中のプロセスを終了します：npx kill-port 3000

デバッグモード

詳細なログを有効にします。

DEBUG=mcp:* npm run start

ログファイル

以下のログを確認します。

• リアルタイムログはコンソール出力
• JQL の学習状況は data/jql-examples.json
• データベースの問題は SQL Server のログ

📈 パフォーマンス監視

利用可能なメトリクス

• データベース接続の状態
• API のレスポンス時間
• JQL クエリの成功率
• メモリ使用パターン
• アクティブなセッション数

ヘルスチェック

# Database health
curl "http://localhost:3000/messages" -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "check database health"}'

# Application status
curl "http://localhost:3000/messages" -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "get application status for MyApp in production"}'

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

開発ガイドライン

• TypeScript のベストプラクティスに従います
• 適切なエラー処理を追加します
• JSDoc コメントを記述します
• データベース操作をテストします
• Zod スキーマですべての入力を検証します

📄 ライセンス

このプロジェクトは ISC ライセンスのもとで公開されています。詳細は package.json ファイルを参照してください。

🆘 サポート

サポートやご質問については、以下をご確認ください。

• 上記のトラブルシューティングのセクションを確認します
• GitHub でプロジェクトの課題を確認します
• MCP Protocol のドキュメントを参照します
• AI 関連の問題については OpenAI API のドキュメントを確認します

---

Model Context Protocol（MCP）を使用して ❤️ を込めて構築