# NestJS MCP Server
NestJSを使用したModel Context Protocol (MCP)サーバーの実装サンプルです。
DDD/クリーンアーキテクチャを適用しやすい構造で、今後のMCP開発のベースとして利用できます。
## 🎯 特徴
- **NestJS**: エンタープライズグレードのフレームワーク
- **デコレーターベース**: `@Tool`デコレーターで簡潔にツールを定義
- **レイヤー分離**: サービス層とツール層を分離（DDD適用可能）
- **依存性注入**: テスタブルで保守性の高い設計
- **Streamable HTTP**: 最新のMCP仕様に対応
- **Zod**: 型安全なパラメータバリデーション
## 🌿 ブランチ構成
このリポジトリは、学習段階に応じて2つのブランチを提供しています：
### `basic-example` ブランチ（初心者向け）
基本的なMCP実装のサンプルです。以下のシンプルな機能を提供します：
- **get_current_time** - 現在の日時を取得
- **calculate** - 四則演算（加算、減算、乗算、除算）
- **save_note** / **get_note** / **list_notes** - メモの保存・取得・一覧表示
**推奨する利用シーン:**
- MCPの基本的な仕組みを学びたい
- NestJSとMCPの連携方法を理解したい
- シンプルな実装例から始めたい
```bash
git checkout basic-example
```
### `main` ブランチ（実践向け）
実用的なFour Keys (DORA Metrics) 実装を含む、より本格的なサンプルです。
**追加機能:**
- GitHub APIを使用したデプロイメント分析
- Four Keys メトリクス計算（デプロイ頻度、リードタイム、変更失敗率、MTTR）
- 包括的なテストカバレッジ（95%以上）
- モック戦略を含むテスト実装例
**推奨する利用シーン:**
- 実際のプロダクション環境での使用を検討している
- GitHub統合などの外部API連携方法を学びたい
- テスト戦略やカバレッジ改善の参考にしたい
## 📦 提供する機能
### basic-exampleブランチ
1. **get_current_time** - 現在の日時を取得
2. **calculate** - 四則演算（加算、減算、乗算、除算）
3. **save_note** - メモの保存
4. **get_note** - メモの取得
5. **list_notes** - 保存されたメモの一覧表示
### mainブランチ（basic-exampleの機能 + 以下）
#### Four Keys (DORA Metrics) ツール
6. **get_deployment_frequency** - デプロイ頻度の計算
- GitHub Releases、Git タグ、GitHub Actions ワークフローから検出
- DORA パフォーマンスレベル評価（Elite/High/Medium/Low）
7. **get_lead_time** - リードタイム（変更のリードタイム）の計算
- PR作成からマージまでの時間を集計
- 平均、中央値、95パーセンタイルを算出
8. **get_change_failure_rate** - 変更失敗率の計算
- ホットフィックスPR、インシデントIssue、ワークフロー失敗から検出
- デプロイ成功率の分析
9. **get_mttr** - MTTR（平均復旧時間）の計算
- インシデントの検出から解決までの時間を集計
- Issue/PRベースのインシデント追跡
10. **get_four_keys_summary** - Four Keys メトリクスの総合サマリー
- 4つのメトリクスを一度に取得
- 総合パフォーマンスレベルの評価
## 🚀 セットアップ
### 1. 依存関係のインストール
```bash
npm install
```
### 2. ビルド
```bash
npm run build
```
### 3. サーバーの起動
```bash
npm start
```
サーバーが起動すると、以下のように表示されます：
```
🚀 NestJS MCP Server running on http://localhost:3000
📡 MCP Endpoint: http://localhost:3000/mcp
```
### 4. テスト実行
```bash
node test-client.mjs
```
### 5. mainブランチ用の追加セットアップ
Four Keys機能を使用する場合、GitHub App認証の設定が必要です。
**📖 詳細な設定手順は [GitHub App 設定ガイド](./docs/GITHUB_APP_SETUP.md) を参照してください。**
#### クイックセットアップ
1. `.env.example`を`.env`にコピー
2. GitHub Appを作成（[詳細手順](./docs/GITHUB_APP_SETUP.md#github-app-の作成手順)）
3. 以下の環境変数を設定：
```bash
GITHUB_APP_ID=your_app_id
GITHUB_INSTALLATION_ID=your_installation_id
GITHUB_PRIVATE_KEY_PATH=path/to/private-key.pem
# または
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
```
**必要なGitHub App権限:**
- Repository permissions:
- Actions: Read
- Contents: Read
- Issues: Read
- Pull requests: Read
- Metadata: Read
## 🏗️ プロジェクト構造
### basic-exampleブランチ
```
src/
├── main.ts # エントリーポイント
├── app.module.ts # ルートモジュール
├── mcp/ # MCPモジュール
│ ├── mcp.module.ts # MCP設定・プロバイダー登録
│ ├── tools/ # ツール層（MCPインターフェース）
│ │ ├── time.tool.ts # 時刻ツール
│ │ ├── calculator.tool.ts # 計算ツール
│ │ └── notes.tool.ts # メモツール
│ └── services/ # サービス層（ビジネスロジック）
│ ├── time.service.ts
│ ├── calculator.service.ts
│ └── notes.service.ts
└── domain/ # ドメイン層（将来の拡張用）
└── notes/
└── (エンティティ、リポジトリなど)
```
### mainブランチ（追加構造）
```
src/
└── mcp/
├── tools/
│ └── four-keys/ # Four Keysツール層
│ ├── deployment-frequency.tool.ts
│ ├── lead-time.tool.ts
│ ├── change-failure-rate.tool.ts
│ ├── mttr.tool.ts
│ └── summary.tool.ts
├── services/
│ ├── github/ # GitHub統合サービス
│ │ ├── github-auth.service.ts # GitHub App認証
│ │ └── github-api.service.ts # GitHub API クライアント
│ └── four-keys/ # Four Keys計算サービス
│ ├── deployment-frequency.service.ts
│ ├── lead-time.service.ts
│ ├── change-failure-rate.service.ts
│ └── mttr.service.ts
└── types/
├── github.types.ts # GitHub API型定義
└── four-keys.types.ts # Four Keys型定義
```
## 📝 実装例
### ツール定義（デコレーターベース）
```typescript
// src/mcp/tools/time.tool.ts
import { Injectable } from '@nestjs/common';
import { Tool } from '@rekog/mcp-nest';
import { z } from 'zod';
import { TimeService } from '../services/time.service';
@Injectable()
export class TimeTool {
constructor(private readonly timeService: TimeService) {}
@Tool({
name: 'get_current_time',
description: '現在の日時を取得します',
parameters: z.object({}),
})
async getCurrentTime() {
const time = this.timeService.getCurrentTime();
return `現在の日時: ${time}`;
}
}
```
### サービス層（ビジネスロジック）
```typescript
// src/mcp/services/time.service.ts
import { Injectable } from '@nestjs/common';
@Injectable()
export class TimeService {
getCurrentTime(): string {
const now = new Date();
return now.toLocaleString('ja-JP', { timeZone: 'Asia/Tokyo' });
}
}
```
### モジュール設定
```typescript
// src/mcp/mcp.module.ts
import { Module } from '@nestjs/common';
import { TimeService } from './services/time.service';
import { TimeTool } from './tools/time.tool';
@Module({
providers: [
// サービス層
TimeService,
// ツール層
TimeTool,
],
})
export class McpToolsModule {}
```
## 🔧 開発
### 開発モード（ホットリロード）
```bash
npm run start:dev
```
### ビルドのみ
```bash
npm run build
```
## 🎓 学習ポイント
### basic-exampleブランチ
#### 1. レイヤー分離
- **ツール層**: MCPプロトコルとのインターフェース（`@Tool`デコレーター）
- **サービス層**: ビジネスロジック（`@Injectable()`）
- **ドメイン層**: エンティティ、リポジトリ（将来の拡張）
#### 2. 依存性注入
```typescript
constructor(private readonly timeService: TimeService) {}
```
コンストラクタインジェクションで疎結合を実現し、テストが容易。
#### 3. 型安全なパラメータ
```typescript
parameters: z.object({
operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
a: z.number(),
b: z.number(),
})
```
Zodによる実行時バリデーションとTypeScript型推論。
#### 4. MCPモジュール設定
```typescript
McpModule.forRoot({
name: 'nestjs-mcp-server',
version: '1.0.0',
transport: McpTransportType.STREAMABLE_HTTP,
mcpEndpoint: '/mcp',
})
```
### mainブランチ（追加の学習ポイント）
#### 5. 外部API統合（GitHub API）
```typescript
@Injectable()
export class GitHubApiService {
private octokit: Octokit | null = null;
constructor(private readonly authService: GitHubAuthService) {}
async listReleases(owner: string, repo: string) {
const client = await this.getClient();
const { data } = await client.rest.repos.listReleases({ owner, repo });
return data;
}
}
```
#### 6. 包括的なテスト戦略（カバレッジ95%以上）
```typescript
// Vitestを使用したモックベースのテスト
describe('DeploymentFrequencyService', () => {
let service: DeploymentFrequencyService;
let mockGitHubApiService: any;
beforeEach(() => {
vi.clearAllMocks();
mockGitHubApiService = {
listReleases: vi.fn().mockResolvedValue(mockReleases),
};
service = new DeploymentFrequencyService(mockGitHubApiService as any);
});
it('リリースベースでデプロイを検出できる', async () => {
const result = await service.calculate('owner', 'repo', 'week', {
method: 'release',
});
expect(result.totalDeployments).toBe(2);
});
});
```
#### 7. GitHub App認証
```typescript
@Injectable()
export class GitHubAuthService {
async getInstallationToken(): Promise<string> {
const auth = createAppAuth({
appId: this.config.appId,
privateKey: this.config.privateKey,
installationId: this.config.installationId,
});
const { token } = await auth({ type: 'installation' });
return token;
}
}
```
#### 8. CI/CD統合
- GitHub Actionsでの自動テスト実行
- カバレッジレポートのPRコメント投稿
- ビルドとテストの自動化
## 🌟 今後の拡張例
### データベース統合
```typescript
// TypeORM
@Module({
imports: [
TypeOrmModule.forRoot({...}),
TypeOrmModule.forFeature([Note]),
],
})
// Prisma
@Injectable()
export class NotesService {
constructor(private prisma: PrismaService) {}
}
```
### 外部API統合
```typescript
@Module({
imports: [HttpModule],
})
@Injectable()
export class ExternalApiService {
constructor(private http: HttpService) {}
}
```
### 認証・認可
```typescript
@Tool({...})
@UseGuards(AuthGuard)
async protectedTool() {...}
```
## 📚 参考リンク
- [NestJS Documentation](https://docs.nestjs.com/)
- [@rekog/mcp-nest](https://github.com/rekog-labs/MCP-Nest)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Zod Documentation](https://zod.dev/)
## 📄 ライセンス
MIT
