KKJ门户MCP服务器

官方网站API的，之MCP服务器实现。

现状设想了如下使用方法。

clone在本地启动
Fork做GitHub Repository需要environment variables, secrets。将出现Cloudflare Workers + KV自主机

概要

这MCP服务器提供从日本官方需求信息门户网站检索·取得采购信息的工具。

主要功能

搜索_通知：查找项目（每次返回10个摘要信息）
获取通知详细信息：获取特定项目的详细信息（包括直接链接至官方门户网站）

特徴

令牌效率：搜索结果仅返回最小信息，详细信息仅在需要时获取
分页：显示10个搜索结果以有效处理大量数据
内存缓存：在进程中保留搜索结果并加快检索速度
回退搜索：缓存错误时也使用附加参数API查找ResultId过滤
多部署模式: Stdio（CLI）、HTTP、Cloudflare Workers対応
API密钥验证：生产环境中的安全访问控制
自动化CI/CD: GitHub Actions自动测试构建

必要要件

Node.js>=20.0.0
npm 或yarn

安装

# 依存関係のインストール
npm install

# ビルド
npm run build

# テスト実行
npm test

部署模式

1. Stdio模式（CLI/Claude Desktop集成）

默认模式。使用标准输入输出MCP与服务器通信。

# 起動
npm start

# または直接実行
node build/index.js

Claude Desktop与集成

Claude Desktop编辑配置文件：

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kkj-portal": {
      "command": "node",
      "args": [
        "/absolute/path/to/kkj-mcp-server/build/index.js"
      ]
    }
  }
}

设置后Claude Desktop中所述修改相应参数的值。

Manus和集成（远程MCP服务器）

Cloudflare Workers部署后Manus在的配置文件中：

macOS/Linux: ~/.config/manus/config.json（或Manus配置文件）

{
  "mcpServers": {
    "kkj-portal": {
      "url": "https://write-your-domain/mcp",
      "transport": "streamable-http"
    }
  }
}

需要认证时:

{
  "mcpServers": {
    "kkj-portal": {
      "url": "https://write-your-domain/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

注意:

URL已实际部署Workers URL中所述方法的备选方法
API_KEYS对话框，您可以在此定义自定义格式Authorization启用页眉API请设置键

2. HTTP服务器模式

HTTP作为服务器启动Web经过MCP可以访问服务器。

# 環境変数を設定して起動
SERVER_MODE=http PORT=3000 npm run start:http

# または開発モード（認証なし）
npm run dev:http

环境变数

.env创建文件（.env.example）：

# サーバーモード
SERVER_MODE=http

# サーバー設定
PORT=3000
HOST=0.0.0.0

# CORS設定
CORS_ORIGIN=*
CORS_CREDENTIALS=false

# API認証（本番環境用）
NODE_ENV=production
API_KEYS=your-api-key-1,your-api-key-2

端点

GET /health -健康检查
GET /mcp/sse - MCP SSE端点
POST /mcp/message - MCP发送消息

使用例

# ヘルスチェック
curl http://localhost:3000/health

# MCPへの接続（SSE）
curl -H "Authorization: Bearer your-api-key" http://localhost:3000/mcp/sse

3. Cloudflare Workers模式（远程MCP服务器）

Cloudflare Workers而需要与环境混合的每条反射光线，进行环境采样。WebStandardStreamableHTTPServerTransport选项卡页面上创建或编辑条目Manus、Claude Desktop（mcp-remote通过代理）、其他MCP可以从客户端连接。

安装过程

KV Namespace创建:

# Wranglerにログイン
wrangler login

# 本番用KV Namespaceを作成
wrangler kv:namespace create "KKJ_CACHE"
# 出力例: { binding = "KKJ_CACHE", id = "abc123..." }

# プレビュー用KV Namespaceを作成
wrangler kv:namespace create "KKJ_CACHE" --preview
# 出力例: { binding = "KKJ_CACHE", preview_id = "xyz789..." }

wrangler.toml配置:

# 上記で取得したIDを設定
[[kv_namespaces]]
binding = "KKJ_CACHE"
id = "abc123..."  # 本番用KV ID
preview_id = "xyz789..."  # プレビュー用KV ID

API设置认证密钥（可选）:

wrangler secret put API_KEYS
# プロンプトで入力: key1,key2,key3

手动部署:

# プレビュー環境へデプロイ
npm run dev:workers  # ローカル開発

# 本番環境へデプロイ
npm run deploy:workers

GitHub Actions自动部署

GitHub Actions的Cloudflare Workers的明细栏样式中定义的设置。

所需设置

GitHub Actions要在中自动部署，请执行以下步骤：Cloudflare和GitHub进行动态观察时的轴心点。

第1步：Cloudflare KV Namespace创建

# Wranglerにログイン
wrangler login

# 本番用KV Namespaceを作成
wrangler kv:namespace create "KKJ_CACHE"
# 出力例:
# ⛅️ wrangler 3.101.0
# ✨ Success!
# Add the following to your configuration file:
# { binding = "KKJ_CACHE", id = "0123456789abcdef0123456789abcdef" }

# プレビュー用KV Namespaceを作成
wrangler kv:namespace create "KKJ_CACHE" --preview
# 出力例:
# ✨ Success!
# Add the following to your configuration file:
# { binding = "KKJ_CACHE", preview_id = "fedcba9876543210fedcba9876543210" }

重要：已输出 id 和 preview_id 请记下。

第2步：Cloudflare获取凭据

CLOUDFLARE_API_TOKEN 创建：

Cloudflare仪表板，仪表板登录
右上角的化身> 我的资料 来修改标记元素的显示属性
左侧菜单> API令牌 来修改标记元素的显示属性
创建令牌 来修改标记元素的显示属性
编辑Cloudflare Workers 单击功能区上 使用模板 来修改标记元素的显示属性
账户资源 选择目标帐户
区域资源 啊 All zones 保持
继续总结 > 创建令牌 来修改标记元素的显示属性
复制显示的标记（无法刷新，请务必记录）

CLOUDFLARE_ACCOUNT_ID 获取：

Cloudflare仪表板，仪表板登录
左侧菜单> 工人和页面 来修改标记元素的显示属性
右边栏的 帐户ID 复制

第3步：GitHub Secrets 配置

存储库>Settings > Secrets and variables > Actions > Secrets 在中添加：

Secret名	値	取得方法
`CLOUDFLARE_API_TOKEN`	`YOUR_CLOUDFLARE_API_TOKEN` 在步骤2中创建API令牌｜
`CLOUDFLARE_ACCOUNT_ID`	`YOUR_ACCOUNT_ID` 在步骤2中获取Account ID
`API_KEYS`	`key1,key2,key3` ｜任意认证密钥（逗号分隔）

例: prod-key-2024,backup-key-2024 选项：不需要认证时不需要设置

设定手顺：

GitHub 在您查看完详细信息后，单击设置选项卡页面上创建或编辑条目
左侧菜单> 秘密和变量 > 行动来修改标记元素的显示属性
秘密用标签 新存储库密钥 来修改标记元素的显示属性
名字的Secret名称秘密赋值
添加机密 来修改标记元素的显示属性
上述三个Secret重复

第4步：GitHub Variables 配置

存储库>Settings > Secrets and variables > Actions > Variables 在中添加：

Variable名	値	取得方法
`KV_NAMESPACE_ID`	`0123456789abcdef...` 在步骤1中获取的生产用KV Namespace ID (`id`)
`KV_NAMESPACE_PREVIEW_ID`	`fedcba9876543210...` 用于在步骤1中获取的预览KV Namespace ID (`preview_id`)

设定手顺：

秘密和变量 > 行动在工作空间的边缘变量选项卡页面上创建或编辑条目
新存储库变量 来修改标记元素的显示属性
名字的Variable名称价值赋值
添加变量 来修改标记元素的显示属性
上述两个Variable重复

部署工作流

部署到预览环境:

PR的 deploy-preview 添加标签
GitHub Actions自动部署到预览环境
部署URL的PR评论

部署到生产环境:

main合并到分支（或push）
自动运行测试
测试成功后进入等待批准状态
批准人手动批准
部署到生产环境

手动触发:

操作>部署到Cloudflare Workers（生产）>运行工作流

检查部署

部署后，可以在以下端点进行健康检查：

# 本番環境
curl https://kkj-mcp-server-prod.YOUR_ACCOUNT_ID.workers.dev/health

# プレビュー環境
curl https://kkj-mcp-server-preview.YOUR_ACCOUNT_ID.workers.dev/health

机能

Web标准流式HTTP: MCP使用的最新传输（可流HTTP）
KV缓存：查找结果和项目详细信息Cloudflare KV保存（带TTL）
全局边：在全球边缘位置运行
自动缩放：根据流量自动缩放
成本效率：从量收费，有免费额度
远程访问：通过互联网可以从任何地方访问

端点

部署后，可以使用以下端点：

GET /health -健康检查
GET /mcp - MCP SSE流建立
POST /mcp - MCP请求提交
DELETE /mcp - MCP会话结束

API密钥验证

验证行为

本番环境（NODE_ENV=production）: API需要密钥
开発环境（NODE_ENV=development）：从开发环境访问时不需要认证
Stdio模式：无认证（基本用于本地运行）

API设置关键帧

# .envファイルまたは環境変数で設定
API_KEYS=key1,key2,key3
NODE_ENV=production

使用方法

HTTP请求Authorization添加页眉：

curl -H "Authorization: Bearer your-api-key" \
     http://your-server/mcp/sse

开発

本地开发

# 監視モード（自動再コンパイル）
npm run watch

# テスト実行
npm test

# カバレッジ付きテスト
npm run test:coverage

# テストUI
npm run test:ui

# MCP Inspectorでテスト
npm run inspector

测试

项目包含44个自动测试：

# 全テスト実行
npm test

# カバレッジレポート生成
npm run test:coverage

# ウォッチモード
npm run test:watch

测试覆盖：

API客户：100%
工具（搜索、详细信息）：100%
XML解析器：66%

使用方法

1.查找项目

search_notices を使って「外壁塗装」に関する東京都の案件を検索してください

参数：

query：搜索关键字（可使用“与”、“或”、“否”和“与”运算符）
project_name: 案件名
organization_name：机关名
lg_code：都道府县代码（13=东京都）
category：类别（1:物品，2:工程，3:劳务）
procedure_type：手续类型
certification：等级（A，B，C，D）
cft_issue_date: 公示日（例: 2025-12-01/, /2025-12-31, 2025-12）
page：页码（默认值：1）

2.获取详细信息

ResultId "12345" の詳細情報を get_notice_details で取得してください

参数：

result_id: search_notices获得ResultId（必需的

回退搜索参数（可选-高速缓存错误时使用）：

project_name：案件名（例：“道路整备工事”）
organization_name: 機関名（例: "国土交通省"）
query：关键字检索（例如：“建设”AND 东京“）
lg_code：都道府县代码（例如“13”）

响应中包含的信息:

项目详细信息（所有字段）
NoticeUrl：直接链接至官方需求门户网站的项目详细信息页面（例如： https://www.kkj.go.jp/d/?D=xxxxx&L=ja）

注意：官方需求API啊ResultId而需要与环境混合的每条反射光线，进行环境采样。缓存ResultId缺少支持的问题 API中查找相应的项目ResultId对较大场景进行渲染期间已观察到该故障。

使用例

基本用法（从高速缓存获取）:

# 先に検索を実行
search_notices で「学校」を検索

# キャッシュから詳細を取得
get_notice_details で ResultId "12345" の詳細を取得

使用回退搜索:

# キャッシュにない場合でも、追加パラメータで取得可能
get_notice_details で ResultId "12345" を project_name "学校改修工事" で取得

查看搜索结果

搜索结果包含以下信息：

ResultId：案件ID（详细取得时に使用）
ProjectName: 案件名
OrganizationName：発注机关
CftIssueDate: 公示日
ExternalDocumentURI：链接至公告文档（可直接访问）
ProjectDescription：案件说明（但默认为最多100个字符）token为了抑制量list在系统中是妥当的处理和认识。完整ProjectDescription啊get_notice_detail），模板名称将采用不同的格式

详细情报（get_notice_details） 除上述内容外：

NoticeUrl：官方需求门户网站的案件详细页面URL
ProjectDescription：案件说明
其他详细信息字段

项目配置

kkj-mcp-server/
├── .github/
│   └── workflows/
│       ├── ci.yml          # CI/CDワークフロー
│       └── dependabot.yml  # 依存関係自動更新
├── src/
│   ├── index.ts            # エントリーポイント（Stdioモード）
│   ├── http.ts             # HTTPサーバーエントリーポイント
│   ├── server.ts           # MCPサーバーメインロジック
│   ├── config/
│   │   ├── server.ts       # サーバー設定
│   │   └── auth.ts         # 認証設定
│   ├── middleware/
│   │   └── auth.ts         # 認証ミドルウェア
│   ├── api/
│   │   ├── client.ts       # 官公需API クライアント
│   │   └── types.ts        # API型定義
│   ├── parsers/
│   │   ├── xml.ts          # XMLパーサー
│   │   └── xml.test.ts     # XMLパーサーテスト
│   └── tools/
│       ├── search.ts       # 検索ツール
│       ├── search.test.ts  # 検索ツールテスト
│       ├── details.ts      # 詳細ツール
│       └── details.test.ts # 詳細ツールテスト
├── build/                  # ビルド成果物
├── .env.example            # 環境変数サンプル
├── .nvmrc                  # Node.jsバージョン指定
├── package.json
├── tsconfig.json
├── vitest.config.ts        # テスト設定
└── README.md

API仕様

官方网站API

贝斯URL: http://www.kkj.go.jp/api/
请求方式：获取
响应格式：XML
字符代码：UTF-8
必須条件: Query, Project_Name, Organization_Name, LG_Code 中的任一个或多个

日付形式

公示日期（cft_issue_date）参数支持以下格式：

YYYY-MM-DD/: 指定日以降
/YYYY-MM-DD：截止日期
YYYY-MM-DD/YYYY-MM-DD：期间指定
YYYY-MM：整个指定月份（自动 YYYY-MM-01/ ），模板名称将采用不同的格式

CI/CD

GitHub Actions自动化：

推/拉请求时:

- 模具检查 - 测试执行（Node.js20.x，22.x） - 构建验证 - 覆盖报告

故障排除

构建错误

# node_modules を削除して再インストール
rm -rf node_modules package-lock.json
npm install
npm run build

HTTP服务器未启动

# 環境変数を確認
echo $SERVER_MODE
echo $PORT

# ログを確認
SERVER_MODE=http PORT=3000 node build/http.js

验证错误

# APIキーが正しく設定されているか確認
echo $API_KEYS

# 開発環境では認証をバイパス
NODE_ENV=development npm run dev:http

Claude Desktop缺少支持的问题

确认配置文件的路径是否为绝对路径
确定构建是否已完成（build/index.js是否存在）
Claude Desktop完全重新启动

调试方法

# MCP Inspectorを使用
npm run inspector

# または直接実行してログ確認
node build/index.js

# HTTPモードのデバッグ
SERVER_MODE=http PORT=3000 node build/http.js

安全注意事项

API密钥由环境变量管理，代码不硬编码
.env文件是.gitignore已添加到

许可证

麻省理工学院

贡献

@gridhra 请以设想在个人及其所属组织中使用为前提进行考虑PR当然欢迎在大的变更的情况下，首先issue中描述的相应参数的值如果有什么问题的话Issue请转告

kkj MCP

快速接入

详细介绍

KKJ门户MCP服务器

概要

主要功能

特徴

必要要件

安装

部署模式

1. Stdio模式（CLI/Claude Desktop集成）

Claude Desktop与集成

Manus和集成（远程MCP服务器）

2. HTTP服务器模式

环境变数

端点

使用例

3. Cloudflare Workers模式（远程MCP服务器）

安装过程

GitHub Actions自动部署

所需设置

第1步：Cloudflare KV Namespace创建

第2步：Cloudflare获取凭据

第3步：GitHub Secrets 配置

第4步：GitHub Variables 配置

部署工作流

检查部署

机能

端点

API密钥验证

验证行为

API设置关键帧

使用方法

开発

本地开发

测试

使用方法

1.查找项目

2.获取详细信息

使用例

查看搜索结果

项目配置

API仕様

官方网站API

日付形式

CI/CD

故障排除

构建错误

HTTP服务器未启动

验证错误

Claude Desktop缺少支持的问题

调试方法

安全注意事项

许可证

相关链接

贡献

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP