cost-management-mcp: Instructions file for Codex

AGENTS | cost-management-mcp

適用範囲 / Scope

• このファイルはリポジトリ直下 (/) に配置され、リポジトリ全体へ適用されます。
• 将来的にパッケージ配下へ AGENTS.md が追加された場合は、"近接優先" ルールに従い、より深い階層の指示を優先してください (Closest file wins)。
• 現在このリポジトリは単一パッケージ構成であり、追加のローカル AGENTS.md は存在しません。

---

1. Overview | 概要

1.1 Mission Statement | 目的

• このリポジトリは Model Context Protocol (MCP) サーバーを実装し、AWS / OpenAI / Anthropic など複数クラウド・API のコストを統合的に分析・可視化します。
• TypeScript (Node.js) ベースで、MCP クライアント (例: Claude Desktop) からの自然言語クエリに応答するツール群を提供します。
• 既存のCI/CD (GitHub Actions) と連携し、品質 (Lint/Typecheck/Test) とセキュリティ (Audit/Secret scan) を自動化しています。

1.2 Architecture Snapshot | アーキテクチャ概観

• ランタイム: Node.js >= 18 (CIでは 18.x / 20.x をサポート)。
• 言語: TypeScript 5.x。CommonJS 出力 (type: "commonjs")。
• フレームワーク: MCP SDK (@modelcontextprotocol/sdk) を用いたツール定義。
• テスト: Jest (ts-jest) によるユニット/統合テスト。カバレッジ収集は Codecov へ送信。
• Lint/Format: ESLint + Prettier (lint-staged と Husky でプリコミット適用)。
• キャッシュ層: node-cache (in-memory)、オプションで Redis (REDIS_URL) を使用可能。
• Secrets 管理: .env or MCP config (例: .mcp.json) を通じて環境変数で渡す。リポジトリには秘匿情報を含めない。

1.3 Directory Map | 主要ディレクトリ

• /src : ソースコード (MCP ツール、サービス、キャッシュ実装)。
• /tests : Jest テストケース。__snapshots__ 等がある場合はここに格納。
• /node_modules : インストール済み依存。原則編集禁止。
• /dist : npm run build で生成される出力。Git管理外。
• /configs ディレクトリは存在しませんが、tsconfig.json / jest.config.js / eslint.config.js / .prettierrc がリポジトリ直下にあります。
• /.github/workflows : GitHub Actions 定義 (ci.yml, release.yml, security.yml 等)。
• .env.example : 必須環境変数のサンプル。実値は追加しないでください。
• mcp-config-example.json, .mcp.json.example : MCP クライアント用設定例。

1.4 Key Entry Points | 重要エントリポイント

• src/index.ts : MCP サーバーの起動ポイント。npm run dev / npm run start で参照。
• src/tools/* : 個別ツール定義 (cost_get, provider_list, etc.)。
• src/services/* : 各クラウド/ベンダーとの通信ロジック。
• src/utils/* : 共通ユーティリティ (キャッシュ、フォーマッタなど)。
• tests/**/*.test.ts : Jest テスト。

1.5 Documentation Cross-Links | 追加資料

• README.md : 機能概要、利用例、バッジ。
• CONTRIBUTING.md : 貢献ガイドライン (コミット規約はConventional Commits推奨)。
• openai-analysis-report.md, billing-apis-research.md : ドメイン調査メモ。
• TEST_RESULTS.md : 過去テスト実行レポート (参考程度)。