Aintent Framework 🚀

Intent MCP Server

自然言語の意図を、構造化された実行可能な形式に変換する Model Context Protocol（MCP）サーバーです。拡張性と信頼性を重視し、意図を管理および処理するための堅牢な API を提供します。

概要

このプロジェクトでは、自然言語の入力を構造化オブジェクトに変換し、実行可能なワークフローを生成する意図処理アーキテクチャを実装しています。意図を管理するための明確な API を提供するとともに、保守性、型安全性、拡張性を重視しています。

機能

• 🎯 意図処理：明確に定義された API を通じて、意図の作成、取得、処理を行います
• 🔍 自然言語理解：ユーザーの生の意図を解析し、理解します
• 🧩 意図の分解：意図を目標と制約を含む構造化オブジェクトに変換します
• 💾 柔軟なストレージ：組み込みのインメモリ実装を備えた、プラグイン可能なストレージシステムです
• 📝 型安全性：包括的な型定義を備えた、完全な TypeScript 実装です
• 🛡️ エラー処理：堅牢なエラー処理およびロギングシステムです
• 🧪 テスト：Jest による包括的なテストスイートです
• 📚 API ドキュメント：明確な API ドキュメントと例を用意しています

前提条件

• Node.js（v18 以降）
• npm または yarn

インストール

1. リポジトリをクローンします：

git clone https://github.com/openpandacodes/intent-mcp-server.git
cd intent-mcp-server

2. 依存関係をインストールします：

npm install

3. ルートディレクトリに .env ファイルを作成します：

cp .env.example .env

4. .env ファイルを更新し、設定を入力します。

設定

サーバーは環境変数を使用して設定できます：

• NODE_ENV：環境（development、production、test）
• PORT：サーバーのポート（デフォルト：3000）
• LOG_LEVEL：ログレベル（debug、info、warn、error）

使用方法

開発

ホットリロードを有効にして開発サーバーを起動します：

npm run dev

本番環境

本番サーバーをビルドして起動します：

npm run build
npm start

テスト

テストを実行します：

npm test

カバレッジ付きでテストを実行します：

npm run test:coverage

API エンドポイント

意図の管理

• POST /api/intent：新しい意図を作成します

  curl -X POST http://localhost:3000/api/intent \
    -H "Content-Type: application/json" \
    -d '{"rawIntent": "Your natural language intent here"}'
  

• GET /api/intent/:id：ID で意図を取得します

  curl -X GET http://localhost:3000/api/intent/YOUR_INTENT_ID
  

その他のエンドポイントについては、API 仕様書に記載されています。

ヘルスチェック

• GET /health：サーバーのヘルスステータスを確認します

アーキテクチャ

サーバーは、それぞれ異なる層からなるクリーンアーキテクチャのパターンに従っています：

1. コントローラー：HTTP リクエストとレスポンスを処理します
2. サービス：中核となるビジネスロジックと意図処理を実装します
3. ストレージ：プラグイン可能な実装を使用してデータを永続化します
4. モデル：データ構造と型を定義します

主なコンポーネント

• IntentController：意図関連の HTTP エンドポイントを処理します
• IntentService：意図処理を担う中核サービスです
• StorageInterface：抽象ストレージ層です
• InMemoryStorage：ストレージインターフェイスの参照実装です

プロジェクト構成

intent-mcp-server/
├── src/
│   ├── controllers/     # HTTP request handlers
│   ├── services/        # Business logic implementation
│   │   └── __tests__/  # Service tests
│   ├── storage/        # Storage implementations
│   ├── models/         # Type definitions
│   └── utils/          # Utility functions
├── tests/              # Test suites
└── config/             # Configuration files

意図の構造

このシステムでは、意図を形式的なオブジェクトに構造化します：

interface Intent {
  id: string;
  rawIntent: string;
  processed: {
    goals: Goal[];
    constraints: Constraint[];
    metadata: Record<string, unknown>;
  };
  status: "pending" | "processing" | "completed" | "failed";
  createdAt: Date;
  updatedAt: Date;
}

エラー処理

サーバーでは、包括的なエラー処理を実装しています：

• エラーの種類ごとのカスタムエラークラス
• 適切な HTTP ステータスコードとエラーレスポンス
• デバッグとモニタリングのための構造化ログ
• TypeScript の型を使用した検証

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'feat: Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

コードが以下の要件を満たしていることを確認してください：

• 既存のスタイルと規約に従っている
• 適切なテストが含まれている
• 必要に応じてドキュメントが更新されている
• Conventional Commits のメッセージを使用している

ライセンス

MIT License — 詳細については LICENSE ファイルを参照してください