Nablarch MCP Server

Nablacch MCP服务器

RAG强化型 模型上下文协议（MCP） 服务器。 纳布拉奇 将框架知识提供给AI编码工具。

概要

Nablarch是面向任务关键系统的Java应用程序框架，但与主流框架相比，社区资源明显不足。本MCP服务器 RAG（检索增强生成） 和 主控程序 结合，为AI工具提供Nablarch的深入知识。

提供机能

• 工具（10个）：语义检索、手持编队设计、代码生成、设置XML验证、API检索、测试生成、故障排除、迁移分析、模式推荐、手持编队优化
• 资源（8URI模式）：处理程序目录、API参考、设计模式、学习指南、示例代码、设置模板、反模式、版本信息
• 提示（6模板）：手册队列设计（setup-handler-queue）、动作创建（create-action）、设置审阅（review-config）、处理程序解说（explain-handler）、迁移指南（migration-guide）、最佳实践（best-practices）
• RAG管线：Nablarch官方文档GitHub113存储库Javadoc Fintan内容的混合搜索（BM25+向量相似度）

体系结构

┌──────────────────────────────────────────────────────────────────┐
│                     AIコーディングツール                            │
│   Claude Code  |  Cursor  |  Copilot  |  VS Code                 │
│   ┌──────────────────────────────────────────────────────────┐   │
│   │                      MCP Client                           │   │
│   └──────────────────────────┬───────────────────────────────┘   │
└──────────────────────────────┼───────────────────────────────────┘
                               │ JSON-RPC 2.0
                               │ STDIO（ローカル）/ Streamable HTTP（リモート）
┌──────────────────────────────▼───────────────────────────────────┐
│              Nablarch MCP Server（Spring Boot）                    │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   MCP Protocol Layer                         │ │
│  │   Tools (10)  |  Resources (8種)  |  Prompts (6)            │ │
│  └──────────────────────────┬──────────────────────────────────┘ │
│                              │                                    │
│  ┌──────────────────────────▼──────────────────────────────────┐ │
│  │                   RAGエンジン（内蔵）                         │ │
│  │   セマンティック検索  |  ハイブリッド検索  |  リランキング       │ │
│  │   Doc Embedder (ONNX bge-m3)  |  Code Embedder (ONNX CodeSage) │ │
│  └──────────────────────────┬──────────────────────────────────┘ │
│                              │                                    │
│  ┌──────────────────────────▼──────────────────────────────────┐ │
│  │              PostgreSQL + pgvector                           │ │
│  │   Docs Index  |  Code Index  |  Javadoc Index  |  Config    │ │
│  └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

动作要件

• Java 17 以上
• Maven 3.9.x（Maven Wrapper同梱）
• PostgreSQL 16+ with pgvector扩张（RAG机能、Phase 2以降）

快速启动

构建

./mvnw package

知识库初始化（可选）

仅当使用嵌入式搜索时请在第一次运行一次。

# 1. pgvectorコンテナ起動 + PostgreSQL初期化
docker compose up -d

# 2. Nablarch公式ドキュメントのEmbedding取込（所要時間: 約20-30分）
bash scripts/init-knowledge.sh

処理内容:

• 关闭Nablarch官方文档（467页）
• 区块分割（约1500区块）
• 在本地ONNX模型（BGE-M3）中生成嵌入式
• 存储在pgvector中

注意:

• init-knowledge.sh 而需要与环境混合的每条反射光线，进行环境采样通过keyword mode（BM25检索）进行动作做
• 嵌入式搜索很精确，但需要很长时间才能初始化
• 重新运行时，将覆盖现有数据（具有幂等性）

执行（STDIO模式）

./mvnw spring-boot:run

在Claude Code中设置

MCP设置文件（.claude/mcp.json）中添加以下内容：

{
  "mcpServers": {
    "nablarch": {
      "command": "java",
      "args": ["-jar", "target/nablarch-mcp-server-0.1.0-SNAPSHOT.jar"]
    }
  }
}

在Docker上运行（Phase4）

docker compose up

技术栈

｜组件｜技术｜选择理由｜ |---|---|---| 语言与Nablarch生态系统的一致性 框架｜弹簧引导3.4.x｜MCP引导器支持｜ |MCP-SDK| MCP Java SDK 0.17.x |公式SDK、Spring AI统合| 与Nablarch生态系统的完整性 标准Java测试 矢量DB矢量搜索集成，成本效率 ｜文档Embedding｜BAAI/bge-m3（ONNX）/Jina v4（API fallback）｜本地免费，可切换配置文件｜ 代码嵌入式（ONNX）/Voyage-code-3（API fallback） 重新排序：提高混合搜索精度 本地开发+远程团队共享

知识来源

RAG管线索引以下Nablarch相关信息源：

｜来源｜内容｜规模｜ |---|---|---| | Nablarch官方文档 ｜体系结构、API规格、开发指南｜数百页｜ | 113存储库（源代码）｜数万文件｜ ｜Javadoc｜所有API参考｜所有模块｜ | 芬拿 学习教材、开发标准｜数十内容｜

项目状态

现在：Phase1-3完成+Phase4-1（基于质量的可观察性）完成。Phase4-2〜4-4未着手。

实施情况摘要

Phase 1: MCP基盘+静的知识（✅ 完了）

• \[x\]项目结构
• \[x\] MCP SDK统合
• x工具存根（search_api，validate_handler_queue）
• \[x\]资源存根（API规格、处理程序规格）
• \[x\] 知识库構造
• \[x\] Tool実装（10个）
• \[x\]资源实现（8URI模式）
• \[x\]Prompt实施（6模板）
• \[x\]MCP检验器测试

Phase2:RAG引擎集成（✅ 已完成

• \[x\]pgvector设置+架构定义
• 文档导入管线
• \[x\]双嵌入式（可切换本地ONNX/AAPI）
• \[x\] semantic_search 工具
• \[x\]混合检索（BM25+矢量检索）
• 重新排序
• \[x\]検索质量评似

Phase3:工具扩充+代码生成（✅ 已完成

• \[x\] design_handler_queue 工具（RAG协作）
• \[x\] generate_code 工具（RAG协作）
• \[x\] generate_test 工具
• \[x\] troubleshoot 工具
• \[x\] analyze_migration 工具
• 可流HTTP传输
• \[x\]所有Prompt模板

已实施质量改进（cmd_066）

P0改善（7件，支持拦截器）:

• DB认证信息的环境变量化（安全性）
• 默认启用HTTP Origin验证（符合MCP规格MUST要求）
• FQCN误り5件修正（情报精度向上）
• version-info.yaml全面更新（最新环境情报反映）
• Tool未登録2件追加（MigrationAnalysisTool，TestGenerationTool）
• 资源提供者未登録6件追加（Api、模式、示例、配置、反模式、版本）
• CI/CD導入（GitHub操作）

P1改善（7件、重要改善）:

• isError:true对应（MCP仕样准据）
• 防止错误消息内部信息曝光
• @ToolParam required=false添加（16个参数）
• DesignHandlerQueueTool二重管理解消（约90行削减）
• SetupHandlerQueuePrompt应用程序类型扩展（添加messaging模板）
• 修正TroubleshootTool Markdown表类型
• FQCN自动验证测试部署（增加131个测试用例）

知识数据扩充（cmd_078）

• 知识YAML文件：10→17文件扩充（覆盖30%→85%）
• 附加区域：数据绑定、验证、日志、邮件、消息、安全性和实用程序

Agent Skills导入（cmd_079）

• .claude/skills/向下属添加6项代理技能
• Nablarch API设计指南、组件XML设置指南、错误处理指南、手持编队设计指南、迁移指南、测试策略指南

Phase4-1：基于质量的可观察性（✅ 已完成

• \[x\] 弹簧靴执行器（健康/信息/指标/普罗米修斯）
• \[x\]3个自定义HealthIndicator+GracefulHealthStatusAggregator
• \[x\]结构化日志（JSON）+请求相关标识
• Counter/Timer/Error
• \[x\] 普罗米修斯連携（/执行器/普罗米修斯）
• \[x\]MCP JSON-RPC请求/响应日志
• \[x\]错误处理统一+SpotBugs/Ceckstyle警告归零
• 兼容pgvector集成测试CI
• \[x\] Tool名snake_case统一

Phase 4-2〜4-4: 未着手

• \[\]Docker Compose部署（Phase4-2）
• \[ \] OAuth 2.0认证（Phase 4-3）
• \[\]自动更新管线/GitHub Webhook（Phase4-4）

已知问题

• Phase4-2-4-4未着手（容器化、安全性、数据管线扩充）

文档

docs/INDEX.md -按读者列出的文档综合指南

｜类别｜内容｜ |---|---| | 导游/ | 🟢 面向用户 -设置、使用方法和可流HTTP设置 | 参考文献/ | 🔵 开发人员 —体系结构、API规范、RAG管线、DB架构 | 设计/ |📐 设计书（Phase 1〜3、全23本）| | 文章/ | 📚 连载报道系列（全17报道的专家培养课程） | 决策/ | 📋 ADR（架构决定记录）｜ | 研究/ | 📊 调查报告、分析资料｜

相关资源

• MCP仕様
• MCP Java SDK
• 春季AI MCP
• Nablarch官方文档
• pg向量

许可证

Apache许可证2.0