# 官報API MCPサーバー

官公需情報ポータルサイトAPI（官報API）をLLMやAIエージェントがツールとして使用できるようにするMCP（Model Context Protocol）サーバーです。

## 機能

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

1. **search_procurements** - 詳細な検索条件で入札情報を検索
2. **get_procurements_by_date** - 指定した日付の入札情報を取得
3. **search_by_keyword** - キーワードで入札情報を検索

## インストール

```bash
cd mcp-kanpo-api
npm install
npm run build
```

## 使用方法

### MCPクライアントでの設定

MCPクライアント（例: Claude Desktop、Cursor等）の設定ファイルに以下を追加してください：

**Claude Desktopの場合** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kanpo-api": {
      "command": "node",
      "args": ["/path/to/mcp-kanpo-api/dist/index.js"]
    }
  }
}
```

**Cursorの場合** (`.cursor/mcp.json` または設定ファイル):

```json
{
  "mcpServers": {
    "kanpo-api": {
      "command": "node",
      "args": ["/path/to/mcp-kanpo-api/dist/index.js"]
    }
  }
}
```

### 開発モード

開発中は `tsx` を使用して直接実行できます：

```bash
npm run dev          # stdio版
npm run dev:http     # HTTP版
```

### HTTPサーバー版の使用方法

n8nなどのHTTPクライアントから使用する場合は、HTTPサーバー版を起動します：

```bash
npm run start:http
```

デフォルトで `http://localhost:3000` で起動します。ポート番号は環境変数 `PORT` で変更できます：

```bash
PORT=8080 npm run start:http
```

#### 利用可能なエンドポイント

- `GET /` - ヘルスチェック
- `GET /api/tools` - 利用可能なツール一覧
- `POST /api/tools/search_procurements` - 入札情報検索
- `POST /api/tools/get_procurements_by_date` - 日付指定取得
- `POST /api/tools/search_by_keyword` - キーワード検索

#### 使用例

```bash
# 日付指定で取得
curl -X POST http://localhost:3000/api/tools/get_procurements_by_date \
  -H "Content-Type: application/json" \
  -d '{"date": "2025-11-07", "count": 50}'

# キーワード検索
curl -X POST http://localhost:3000/api/tools/search_by_keyword \
  -H "Content-Type: application/json" \
  -d '{"keyword": "情報システム", "count": 20}'
```

#### ngrokでの公開

ngrokを使用してHTTPサーバーを外部公開できます：

```bash
# 1. HTTPサーバーを起動
npm run start:http

# 2. 別のターミナルでngrokを起動
ngrok http 3000

# 3. ngrokが提供するURL（例: https://xxxx-xxxx-xxxx.ngrok-free.app）をn8nで使用
```

### 自然言語での使用方法

このMCPサーバーは、LLM/AIエージェント（Claude、GPT-4等）が自然言語の命令を理解して、適切なツールを自動的に呼び出すことを想定しています。

**使用例:**

- 「2025年11月7日の入札情報を取得して」→ `get_procurements_by_date` ツールが自動的に呼び出されます
- 「情報システムというキーワードで検索して」→ `search_by_keyword` ツールが自動的に呼び出されます
- 「東京都の物品カテゴリーの入札情報を検索して」→ `search_procurements` ツールが自動的に呼び出されます
- 「11月の役務カテゴリーの入札情報を検索して」→ `search_procurements` ツールが自動的に呼び出されます

LLM/AIエージェントは、あなたの自然言語の命令を理解し、適切なツールとパラメータを選択して実行します。

## 利用可能なツール

### 1. search_procurements

詳細な検索条件で入札情報を検索します。

**パラメータ:**
- `query` (string, 任意): 検索文字列（AND、OR、NOT演算子使用可能）
- `projectName` (string, 任意): 件名で絞り込み
- `organizationName` (string, 任意): 機関名で絞り込み
- `lgCode` (string, 任意): 都道府県コード（JIS X0401準拠）
- `category` (number, 任意): カテゴリー（1=物品, 2=工事, 3=役務）
- `procedureType` (number, 任意): 公示種別（1=一般競争入札, 2=簡易公募型競争入札, 3=簡易公募型指名競争入札）
- `certification` (string, 任意): 入札資格（A, B, C, D）
- `cftIssueDate` (string, 任意): 公告日（形式: YYYY-MM-DD/ または /YYYY-MM-DD または YYYY-MM-DD/YYYY-MM-DD）
- `tenderSubmissionDeadline` (string, 任意): 入札開始日
- `openingTendersEvent` (string, 任意): 開札日
- `periodEndTime` (string, 任意): 納入期限日
- `count` (number, 任意): 返却件数（デフォルト: 100、最大: 1000）

**注意:** `query`、`projectName`、`organizationName`、`lgCode`のいずれか一つを指定することを推奨します。すべてが指定されない場合は、デフォルトで`Query="*"`が使用されます。

### 2. get_procurements_by_date

指定した日付の入札情報を取得します。内部では`query="入札"`と`cftIssueDate`を指定して検索を実行します。

**パラメータ:**
- `date` (string, 必須): 日付（形式: YYYY-MM-DD）
- `count` (number, 任意): 返却件数（デフォルト: 100、最大: 1000）

**例:**
```json
{
  "date": "2025-11-07",
  "count": 50
}
```

### 3. search_by_keyword

キーワードで入札情報を検索します。

**パラメータ:**
- `keyword` (string, 必須): 検索キーワード
- `count` (number, 任意): 返却件数（デフォルト: 100、最大: 1000）

**例:**
```json
{
  "keyword": "情報システム",
  "count": 20
}
```

## レスポンス形式

### MCP版（stdio）

すべてのツールは以下の形式でレスポンスを返します：

```json
{
  "searchHits": 262,
  "results": [
    {
      "resultId": 1,
      "key": "...",
      "externalDocumentURI": "https://...",
      "projectName": "第2069号小中学校児童生徒用机・いす",
      "date": "2025-11-07T19:08:01+09:00",
      "fileType": "pdf",
      "fileSize": 134411,
      "lgCode": "19",
      "prefectureName": "山梨県",
      "cityCode": "192015",
      "cityName": "甲府市",
      "organizationName": "山梨県甲府市",
      "cftIssueDate": "2025-11-07T00:00:00+09:00",
      "category": "物品",
      "procedureType": "一般競争入札",
      "projectDescription": "...",
      "attachments": [
        {
          "name": "入札説明書（PDF：132KB）",
          "uri": "https://..."
        }
      ]
    }
  ]
}
```

### HTTP版

HTTPサーバー版は以下の形式でレスポンスを返します：

```json
{
  "success": true,
  "data": {
    "searchHits": 262,
    "results": [
      {
        "resultId": 1,
        "projectName": "第2069号小中学校児童生徒用机・いす",
        "organizationName": "山梨県甲府市",
        "cftIssueDate": "2025-11-07T00:00:00+09:00",
        "category": "物品",
        "procedureType": "一般競争入札",
        ...
      }
    ]
  }
}
```

エラーの場合：

```json
{
  "success": false,
  "error": "エラーメッセージ"
}
```

## 注意事項

- このAPIは官公需情報ポータルサイトのAPIを使用しています
- 登録・認証は不要で誰でも利用可能です
- 利用規約を遵守してください
- APIのレスポンスはXML形式ですが、このMCPサーバーはJSON形式に変換して返します

## 参考資料

- [官公需情報ポータルサイト](https://www.kkj.go.jp/)
- [APIガイド](https://www.kkj.go.jp/doc/ja/api_guide.pdf)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## ライセンス

MIT