Development

git clone https://github.com/Strom-Capital/mcp-server-db2i.git
cd mcp-server-db2i

nvm use
npm install

DB2I_HOSTNAME=your-ibm-i-host.com
DB2I_USERNAME=your-username
DB2I_PASSWORD=your-password
DB2I_SCHEMA=your-schema

# Development settings
LOG_LEVEL=debug
LOG_PRETTY=true

npm run dev

mcp-server-db2i/
├── src/
│   ├── index.ts           # Entry point: startup checks, transports, shutdown
│   ├── cli.ts             # Command-line flags and validate-tools
│   ├── server.ts          # MCP server factory and tool registration
│   ├── systems.ts         # DB2I_PROFILES and the per-call target system
│   ├── resources.ts       # MCP resources and name completion
│   ├── prompts.ts         # MCP prompts
│   ├── config.ts          # Configuration loading
│   ├── openapi.ts         # OpenAPI specification
│   ├── auth/              # Authentication (HTTP): tokens and middleware
│   ├── db/                # Database layer
│   │   ├── connection.ts  # Connection pools per caller and system
│   │   ├── driver.ts      # Driver interface
│   │   ├── drivers/       # jt400, odbc and mapepire implementations
│   │   ├── queries.ts     # Catalog queries
│   │   ├── sqlErrorInfo.ts # Cause and recovery for failed statements
│   │   ├── indexAdvice.ts # index_advice from SYSIXADV
│   │   ├── routines.ts    # list_routines and describe_routine from SYSROUTINES and SYSPARMS
│   │   ├── profile.ts     # profile_table statistics
│   │   └── sqlServices.ts # PARSE_STATEMENT, GENERATE_SQL, RELATED_OBJECTS
│   ├── customTools/       # YAML business SQL tools, annotations, masking, file watch
│   ├── tools/             # MCP tools
│   │   ├── query.ts       # execute_query
│   │   ├── sqlLimit.ts    # FETCH FIRST row cap
│   │   ├── metadata.ts    # Schema, table, and catalog search tools
│   │   ├── indexAdvice.ts # index_advice
│   │   ├── routines.ts    # list_routines, describe_routine
│   │   ├── profile.ts     # profile_table
│   │   └── sqlServices.ts # validate_query, DDL, related objects, journals
│   ├── transports/        # HTTP transport
│   │   ├── http.ts        # Express server and /auth
│   │   ├── sessionAuth.ts # Session key per auth mode
│   │   └── sessionManager.ts
│   └── utils/
│       ├── logger.ts      # Structured logging
│       ├── auditLog.ts    # One JSON line per tool call
│       ├── formatResult.ts # json, pretty, and markdown tool text
│       ├── rateLimiter.ts # Rate limiting
│       └── security/      # SQL validation and schema allowlist
├── tests/                 # Unit and integration tests (no IBM i needed)
├── examples/              # Business SQL tools and a profiles file
├── docs/                  # Documentation
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
└── vitest.config.ts

npm test

npm run test:watch

npm run test -- --coverage

npm run test -- tests/integration/

npx mcp-server-db2i validate-tools examples/erp-tools

npx mcp-server-db2i validate-tools --connect examples/erp-tools

      - name: Validate tool files
        run: npx mcp-server-db2i validate-tools examples/erp-tools

npm run lint:fix

// src/tools/myTool.ts
import type { DbTarget } from '../systems.js';
import { createChildLogger } from '../utils/logger.js';

const log = createChildLogger({ component: 'my-tool' });

export interface MyToolInput {
  param1: string;
  param2?: number;
  target?: DbTarget;  // Caller and IBM i system; omit for the stdio default
}

export async function myTool(input: MyToolInput): Promise<{
  success: boolean;
  data?: unknown;
  error?: string;
}> {
  log.debug({ input }, 'Executing myTool');
  
  try {
    // Implementation
    return { success: true, data: result };
  } catch (err) {
    log.error({ err }, 'myTool failed');
    // Type-safe error handling
    const message = err instanceof Error ? err.message : String(err);
    return { success: false, error: message };
  }
}

if (enabledTools.has('my_tool')) {
  server.registerTool(
    'my_tool',
    {
      title: 'My Tool',
      description: 'Description of what this tool does',
      annotations: READ_ONLY_ANNOTATIONS,
      inputSchema: z.object({
        ...system,
        param1: z.string().describe('First parameter'),
        param2: z.number().optional().describe('Optional second parameter'),
      }),
      outputSchema: myToolOutputSchema,
    },
    withToolHandler(
      (args, target) => myTool({ ...args, target }),
      'My tool failed',
      sessionContext,
      argsAudit('my_tool'),
    )
  );
}

// tests/myTool.test.ts
import { describe, it, expect } from 'vitest';
import { myTool } from '../src/tools/myTool.js';

describe('myTool', () => {
  it('should return success for valid input', async () => {
    const result = await myTool({ param1: 'test' });
    expect(result.success).toBe(true);
  });
});

// Global pool (stdio)
initializePool(config);
const result = await executeQuery(sql, params);

// Session pool (HTTP)
initializeSessionPool(sessionId, config);
const result = await executeQuery(sql, params, sessionId);
closeSessionPool(sessionId);

export async function myQuery(
  param: string,
  sessionId?: string
): Promise<MyResult[]> {
  const sql = `
    SELECT COLUMN1, COLUMN2
    FROM QSYS2.MY_VIEW
    WHERE FIELD = ?
  `;
  
  const result = await executeQuery(sql, [param], sessionId);
  return result.rows.map(row => ({
    column1: String(row.COLUMN1 || '').trim(),
    column2: Number(row.COLUMN2 || 0),
  }));
}

app.get('/my-endpoint', authMiddleware, async (req, res) => {
  // Implementation
  res.json({ status: 'ok' });
});

import { authMiddleware, AuthenticatedRequest } from '../auth/index.js';

app.get('/protected', authMiddleware, (req, res) => {
  const authReq = req as AuthenticatedRequest;
  const session = authReq.tokenSession;
  // Use session.config for DB operations
});

LOG_LEVEL=debug npm run dev

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["tsx", "src/index.ts"],
      "envFile": "${workspaceFolder}/.env",
      "console": "integratedTerminal"
    }
  ]
}

git clone https://github.com/YOUR-USERNAME/mcp-server-db2i.git

git checkout -b feature/my-feature

git commit -m "feat: add new tool for X"
git commit -m "fix: handle edge case in Y"
git commit -m "docs: update configuration guide"

git push origin feature/my-feature