digimangos-work-demo/cobol-indexer-mcp-server

COBOL MCP Server

A Model Context Protocol (MCP) server that provides COBOL function extraction capabilities. This server enables LLMs to interact with COBOL codebases by indexing and extracting functions, sections, paragraphs, and procedures from COBOL files.

Features

• Workspace Indexing: Automatically scan workspace for COBOL files (.cob, .cobol, .cbl)
• Function Extraction: Parse and extract COBOL functions, sections, paragraphs, and procedures
• Smart Search: Search functions by name patterns with wildcard and regex support
• Code Retrieval: Extract complete function code with line numbers and context
• Multiple Dialects: Support for various COBOL dialects (COBOL-85, Enterprise COBOL, etc.)

Requirements

• Node.js 18 or newer
• VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client

Installation

npm install @cobol/mcp

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "cobol": {
      "command": "npx",
      "args": ["@cobol/mcp"]
    }
  }
}

With Configuration

{
  "mcpServers": {
    "cobol": {
      "command": "npx",
      "args": ["@cobol/mcp", "--config", "cobol-config.json"]
    }
  }
}

Command Line Options

npx @cobol/mcp [options]

Options:
  --config <path>    Path to configuration file
  --root <path>      Root path to scan for COBOL files (default: current directory)
  --port <number>    Port for HTTP transport (default: stdio)
  --debug            Enable debug logging
  --help, -h         Show help message

Configuration

Create a cobol-config.json file:

{
  "workspace": {
    "rootPaths": ["./src", "./legacy"],
    "includePatterns": ["**/*.cob", "**/*.cobol", "**/*.cbl"],
    "excludePatterns": ["**/backup/**", "**/temp/**"],
    "maxFileSize": 10485760
  },
  "parser": {
    "dialect": "cobol-85",
    "extractComments": true,
    "columnFormat": "fixed"
  },
  "functions": {
    "extractTypes": ["section", "paragraph", "procedure", "program"],
    "includeLineNumbers": true,
    "includeContext": true,
    "minimumLines": 1
  },
  "indexing": {
    "autoIndex": true,
    "maxFunctionsPerFile": 1000
  }
}

MCP Tools

cobol_index_workspace

Scan workspace for COBOL files and build function index.

Parameters:

• rootPaths (optional): Array of root paths to scan
• includePatterns (optional): File patterns to include
• excludePatterns (optional): File patterns to exclude

cobol_list_functions

List all indexed COBOL functions with optional filtering.

Parameters:

• type (optional): Filter by function type (section, paragraph, procedure, program)
• division (optional): Filter by division (identification, environment, data, procedure)
• filePath (optional): Filter by file path

cobol_get_function

Extract complete function code by name.

Parameters:

• name (required): Name of the function to extract
• includeLineNumbers (optional): Include line numbers in output
• includeContext (optional): Include surrounding context

cobol_search_functions

Search functions by name pattern or content.

Parameters:

• pattern (required): Search pattern (supports wildcards or regex)
• regex (optional): Treat pattern as regular expression
• caseSensitive (optional): Case-sensitive search
• type (optional): Filter by function type

Examples

Basic Usage

# Index current directory
npx @cobol/mcp --root .

# Index specific COBOL project
npx @cobol/mcp --root /path/to/cobol/project

With MCP Client

Once connected to an MCP client, you can use these commands:

# Index the workspace
Use tool: cobol_index_workspace with rootPaths: ["/path/to/cobol/files"]

# List all functions
Use tool: cobol_list_functions

# Get specific function
Use tool: cobol_get_function with name: "CALCULATE-PAYROLL"

# Search functions
Use tool: cobol_search_functions with pattern: "*CALC*"

Supported COBOL Constructs

• Programs: PROGRAM-ID declarations
• Sections: Named sections in PROCEDURE DIVISION
• Paragraphs: Named paragraphs in PROCEDURE DIVISION
• Procedures: General procedure constructs

File Formats

• Fixed format (traditional 72-column COBOL)
• Free format (modern COBOL)
• Auto-detection of format

Logging and Debugging

The COBOL MCP server includes comprehensive logging and debugging capabilities. Configure logging using environment variables:

Environment Variables

• COBOL_LOG_LEVEL: Set logging level (error, warn, info, debug, trace)
• COBOL_DEBUG=true: Enable debug mode
• COBOL_VERBOSE=true: Enable verbose mode with detailed context
• NO_COLOR=true: Disable colored output

Examples

# Enable debug logging
COBOL_DEBUG=true echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cobol_index_workspace","arguments":{"rootPaths":["./src"]}}}' | node cli.js

# Verbose logging with timing information
COBOL_VERBOSE=true echo '...' | node cli.js

# Only show errors
COBOL_LOG_LEVEL=error echo '...' | node cli.js

For detailed logging documentation, see .

Dependencies

• Node.js 18+
• Model Context Protocol SDK

License

Apache-2.0

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development

# Clone the repository
git clone https://github.com/microsoft/cobol-mcp.git
cd cobol-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev