IRIS MCP Server

A Model Context Protocol (MCP) server that provides AI agents with tools and prompts to interact with InterSystems IRIS databases.

Features

MCP Tools

This MCP server exposes a unified tool for database interaction with three operations:

1. list_tables - Lists all tables in the SQLUser schema
2. list_columns - Retrieves column definitions for a specific table
3. query - Executes SELECT queries against the database (read-only for security)

MCP Prompts

The server provides three standardized prompts following MCP 2025 specification to help AI agents use the tools effectively:

1. explore-database - Guides users to discover available tables in the SQLUser schema
2. analyze-table - Guides users to understand table structure and column metadata
3. query-data - Guides users to query data with proper SQL syntax and IRIS-specific considerations

Prerequisites

• Node.js 18 or higher
• Access to an InterSystems IRIS database
• Database credentials (host, port, namespace, username, password)

Installation

npm install

Configuration

Create a .env file in the project root with your IRIS database credentials:

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

You can copy .env.example as a starting point:

cp .env.example .env

Usage

Build the project

npm run build

Start the MCP server

npm start

The server runs on stdio transport and follows the MCP protocol for communication with AI agents.

Development mode

Watch for changes and rebuild automatically:

npm run watch

MCP Tools

iris tool

The unified iris tool supports three operations through the operation parameter.

Operation: list_tables

Lists all tables in the SQLUser schema.

Parameters:

• operation: "list_tables" (required)

Example:

{
  "operation": "list_tables"
}

Operation: list_columns

Get detailed column information for a specific table.

Parameters:

• operation: "list_columns" (required)
• table_name (required): Name of the table

Example:

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

Operation: query

Execute a SELECT query against the database.

Parameters:

• operation: "query" (required)
• query (required): SQL SELECT query to execute
• max_rows (optional): Maximum rows to return (default: 100, max: 1000)

Example:

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

Security: Only SELECT queries are allowed. Queries containing DROP, DELETE, INSERT, UPDATE, etc. will be rejected.

MCP Prompts

explore-database

Helps users discover what tables are available in the database.

Arguments: None

analyze-table

Helps users understand the structure of a specific table.

Arguments:

• table_name (required): The table to analyze

query-data

Helps users formulate and execute SQL queries effectively.

Arguments:

• query_description (required): Description of what data to retrieve
• table_name (optional): Primary table to query
• max_rows (optional): Maximum rows to return

Testing

Run all tests

npm run test:all

Run specific test suites

# 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 Inspector

The project includes the official MCP Inspector for interactive testing and debugging.

UI Mode (Interactive)

npm run test:inspector

This opens a web interface where you can:

• Explore available tools and prompts
• Test tool calls with different parameters
• View request/response cycles
• Debug MCP server behavior

CLI Mode (Automated)

npm run test:inspector:cli

Runs automated tests using the MCP Inspector CLI.

Docker

Using Docker Compose

The project includes Docker Compose configuration for running both IRIS database and the MCP server.

Start services

docker compose up -d

This starts:

• InterSystems IRIS Community Edition on ports 1972 and 52773
• MCP Server connected to IRIS

View logs

docker compose logs -f mcp-server

Stop services

docker compose down

Rebuild MCP server image

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

Environment Variables

Configure via .env file or environment:

• IRIS_HOST: IRIS database host (default: localhost, docker: iris)
• IRIS_PORT: IRIS database port (default: 1972)
• IRIS_NAMESPACE: IRIS namespace (default: USER)
• IRIS_USERNAME: Database username (default: _SYSTEM)
• IRIS_PASSWORD: Database password (default: SYS)
• IRIS_DEFAULT_SCHEMA: Default schema for queries (default: SQLUser)

Project Structure

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

The project includes a comprehensive CI/CD pipeline that runs automatically on every push and pull request.

Workflow Jobs

1. Test Suite

   • Sets up InterSystems IRIS database as a service
   • Runs all test suites (integration, prompts, security, schema)
   • Generates test reports and uploads artifacts
   • Ensures code quality before merging

2. Lint and Type Check

   • Validates TypeScript compilation
   • Ensures code meets quality standards

3. Security Scan

   • Runs npm audit for dependency vulnerabilities
   • Generates security reports
   • Flags potential security issues

4. Docker Build (main branch only)

   • Builds Docker image after successful tests
   • Validates Docker configuration
   • Uses build cache for faster builds

5. Summary

   • Generates comprehensive CI pipeline summary
   • Reports status of all jobs
   • Provides commit and branch information

Workflow Triggers

• Push: Runs on main and develop branches
• Pull Request: Runs on PRs targeting main or develop
• Manual: Can be triggered manually via workflow_dispatch

Artifacts

The CI pipeline generates and uploads:

• Test reports (30-day retention)
• Build artifacts (7-day retention)
• Security audit reports (30-day retention)

See .github/workflows/ci.yml for the complete workflow configuration.

Development

The project uses TypeScript and compiles to ES modules. All imports use absolute paths with .js extensions for proper ESM resolution.

Code Quality

• TypeScript for type safety
• Zod for runtime schema validation
• Comprehensive test coverage (47 tests across 4 suites)
• Security-first design (read-only queries)
• Automated CI/CD with GitHub Actions

Testing Strategy

Following MCP 2025 best practices:

• Integration testing with real database connections
• Security testing for SQL injection prevention
• Schema validation for MCP compliance
• Prompt testing for AI agent usability
• Automated testing in CI/CD pipeline

See ADR/001-testing-strategy.md for complete testing documentation.

Security

• Read-only operations: Only SELECT queries are allowed
• SQL injection prevention: Dangerous keywords are blocked
• Input validation: All parameters validated with Zod schemas
• Non-root Docker user: MCP server runs as non-privileged user

License

MIT