AI导哈

数据库交互协议服务器

IRIS MCP Server是一个基于Model Context Protocol（MCP）的服务器，为AI代理提供与InterSystems IRIS数据库交互的工具和提示。

  • by GytNGF
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 GytNGF/iris-mcp

使用说明

IRIS MCP 服务器

一个模型上下文协议（MCP）服务器，为AI代理提供工具和提示，以便与InterSystems IRIS数据库进行交互。

特点/特性

MCP 工具

这个MCP服务器提供了一个统一的工具，用于数据库交互，包含三种操作：

  1. 列出表（或表格列表） - 列出SQLUser模式中的所有表
  2. list_columns（可翻译为“列列表”或根据上下文具体翻译为相应的列名列表） - 获取特定表的列定义
  3. 查询 - 对数据库执行SELECT查询（出于安全考虑，仅读取）

MCP 提示（或“MCP 提醒”）

服务器遵循MCP 2025规范，提供三个标准化提示，以帮助AI代理有效使用工具：

  1. 探索数据库 - 引导用户发现SQLUser架构中的可用表
  2. 分析表格 - 引导用户理解表结构和列元数据
  3. 查询数据 - 引导用户使用正确的SQL语法和IRIS特定的考虑因素来查询数据

先决条件

  • Node.js 18 或更高版本
  • 访问InterSystems IRIS数据库
  • 数据库凭据（主机、端口、命名空间、用户名、密码）

安装

npm install

配置

创建一个 .env 在项目根目录下创建一个文件，包含您的IRIS数据库凭据：

IRIS_HOST=localhost
IRIS_PORT=1972
IRIS_NAMESPACE=USER
IRIS_USERNAME=_SYSTEM
IRIS_PASSWORD=SYS
IRIS_DEFAULT_SCHEMA=SQLUser

你可以复制 .env.example 作为起点：

cp .env.example .env

用法

构建项目

npm run build

启动MCP服务器

npm start

该服务器运行在stdio传输层上，并遵循MCP协议与AI代理进行通信。

开发模式

监控变化并自动重建：

npm run watch

MCP 工具

虹膜工具

统一的 iris 该工具支持三种操作，通过 operation 参数。

操作：列出表（list_tables）

列出 SQLUser 架构中的所有表。

参数：

  • operation“list_tables”（必需）

示例：

{
  "operation": "list_tables"
}

操作：列出列（或“显示列名”）

获取特定表的详细列信息。

参数：

  • operation"list_columns"（必需）
  • table_name （必填）：表名

示例：

{
  "operation": "list_columns",
  "table_name": "Users"
}

操作：查询

对数据库执行一个SELECT查询。

参数：

  • operation“query”（必需）
  • query （必需）：要执行的SQL SELECT查询
  • max_rows （可选）：要返回的最大行数（默认：100，最大：1000）

示例：

{
  "operation": "query",
  "query": "SELECT * FROM Users WHERE IsActive = 1",
  "max_rows": 50
}

安全性： 仅允许执行SELECT查询。包含DROP、DELETE、INSERT、UPDATE等操作的查询将被拒绝。

MCP 提示

探索数据库

帮助用户发现数据库中可用的表。

参数： 无

分析表格

帮助用户理解特定表的结构。

参数：

  • table_name （必需）：要分析的表格

查询数据

帮助用户有效制定和执行SQL查询。

参数：

  • query_description （必填）：要检索的数据的描述
  • table_name （可选）：要查询的主要表
  • max_rows （可选）：要返回的最大行数

测试

运行所有测试

npm run test:all

运行特定的测试套件

# Integration tests
npm run test:integration

# Prompt tests
npm run test:prompts

# Security tests
npm run test:security

# Schema validation tests
npm run test:schema

MCP检查员

该项目包含了用于交互式测试和调试的官方MCP Inspector工具。

用户界面模式（交互式）

npm run test:inspector

这将打开一个网页界面，在其中您可以：

  • 探索可用的工具和提示
  • 使用不同参数调用测试工具
  • 查看请求/响应周期
  • 调试MCP服务器行为

CLI 模式（自动化）

npm run test:inspector:cli

使用MCP Inspector CLI运行自动化测试。

Docker

使用 Docker Compose

该项目包含用于同时运行IRIS数据库和MCP服务器的Docker Compose配置。

启动服务

docker compose up -d

这开始了：

  • InterSystems IRIS 社区版运行在端口 1972 和 52773 上
  • MCP服务器已连接到IRIS

查看日志

docker compose logs -f mcp-server

停止服务

docker compose down

重建MCP服务器镜像

docker compose build mcp-server
docker compose up -d mcp-server

环境变量

通过（某种方式）进行配置 .env 文件或环境：

  • IRIS_HOSTIRIS数据库主机（默认：localhost，Docker环境：iris）
  • IRIS_PORTIRIS数据库端口（默认：1972）
  • IRIS_NAMESPACEIRIS 命名空间（默认：USER）
  • IRIS_USERNAME数据库用户名（默认：_SYSTEM）
  • IRIS_PASSWORD数据库密码（默认：SYS）
  • IRIS_DEFAULT_SCHEMA查询的默认模式（默认：SQLUser）

项目结构

iris-mcp/
├── src/
│   ├── index.ts                 # Main MCP server implementation
│   ├── db/
│   │   └── connection.ts        # IRIS database connection management
│   ├── tools/
│   │   └── iris-tool.ts         # Unified IRIS tool with three operations
│   └── prompts/
│       └── iris-prompts.ts      # MCP prompts definitions
├── tests/
│   ├── integration/             # Integration tests for tool operations
│   ├── prompts/                 # Prompt functionality tests
│   ├── security/                # SQL injection and security tests
│   └── schema/                  # Schema validation tests
├── dist/                        # Compiled JavaScript output
├── Dockerfile                   # Docker image for MCP server
├── docker-compose.yml           # Docker Compose configuration
├── package.json
├── tsconfig.json
└── .env                         # Database configuration (not in repo)

持续集成/持续交付（CI/CD）

GitHub Actions

该项目包含一个全面的持续集成/持续交付（CI/CD）流水线，该流水线会在每次推送和拉取请求时自动运行。

工作流任务

  1. 测试套件

    • 将InterSystems IRIS数据库设置为服务
    • 运行所有测试套件（集成测试、提示测试、安全测试、模式测试）
    • 生成测试报告并上传工件
    • 确保合并前的代码质量

  2. Lint 和类型检查

    • 验证TypeScript编译
    • 确保代码符合质量标准

  3. 安全扫描

    • 运行 npm audit 检查依赖项漏洞
    • 生成安全报告
    • 标记潜在的安全问题

  4. Docker 构建 （仅限主分支）

    • 在测试成功后构建Docker镜像
    • 验证Docker配置
    • 使用构建缓存以加快构建速度

  5. 摘要

    • 生成全面的持续集成（CI）流水线总结
    • 报告所有作业的状态
    • 提供提交和分支信息

工作流触发器

  • 推动；推送运行于 main 并且 develop 分支
  • **拉取请求（或称为“合并请求”）**在针对的拉取请求（PRs）上运行 main 或者 develop
  • 手册可以通过 workflow_dispatch 手动触发

文物（或遗迹）

CI流水线生成并上传：

  • 测试报告（保留30天）
  • 构建产物（保留7天）
  • 安全审计报告（保留30天）

见 .github/workflows/ci.yml 用于完整的流程配置。

发展

该项目使用TypeScript编写，并编译为ES模块。所有导入均使用绝对路径 .js 用于实现适当ESM（地球系统模式）分辨率的扩展。

代码质量

  • 使用TypeScript确保类型安全
  • 用于运行时模式验证的Zod
  • 全面的测试覆盖率（4个测试套件共47项测试）
  • 安全优先设计（仅读查询）
  • 使用GitHub Actions实现自动化CI/CD

测试策略

遵循MCP 2025的最佳实践：

  • 使用真实数据库连接进行集成测试
  • 针对SQL注入预防的安全测试
  • MCP合规性的模式验证
  • 针对AI代理可用性的快速测试
  • 在CI/CD流水线中的自动化测试

见 ADR/001-测试策略.md 以获取完整的测试文档。

安全

  • 只读操作仅允许使用SELECT查询
  • 防止SQL注入危险关键词已被屏蔽
  • 输入验证所有参数均通过Zod模式验证
  • 非root权限的Docker用户MCP服务器以非特权用户身份运行

许可证

麻省理工学院（MIT）

相关 MCP