COBOL MCP Server

A Model Context Protocol (MCP) server implementation written in COBOL. This server provides tools for tax calculations and demonstrates how COBOL can be used to build modern API services.

Overview

This project implements an MCP server that communicates via JSON-RPC 2.0 over stdin/stdout. It provides:

• Tax Calculation Tool: Calculate 7.5% sales tax on any amount
• MCP Protocol Compliance: Supports initialize, tools/list, tools/call, and ping methods

Project Structure

cbl-mcp-server/
├── src/
│   ├── server.cbl           # Main entry point and request loop
│   ├── transport.cbl        # I/O handling (read request, write response)
│   ├── parser.cbl           # JSON-RPC request parsing
│   ├── dispatcher.cbl       # Method routing
│   ├── response-builder.cbl # JSON-RPC response builders
│   └── tax-service.cbl      # Tax calculation logic
├── copybooks/
│   ├── CONSTANTS.cpy        # Protocol version constant
│   ├── STATUS.cpy           # Status flags (EOF, parsed)
│   ├── REQUEST.cpy          # Request data structure
│   ├── RESPONSE.cpy          # Response buffer structure
│   └── TOOL.cpy             # Tool definitions
├── Makefile                 # Build configuration
├── Dockerfile               # Container build
└── README.md                # This file

Prerequisites

• GnuCOBOL compiler (cobc)
• Make build tool
• Docker (optional, for containerized deployment)

Installing GnuCOBOL

Ubuntu/Debian:

sudo apt-get install gnucobol make

macOS (Homebrew):

brew install gnucobol

Building

Local Build

make

This produces the mcp-server executable.

Docker Build

docker build -t cbl-mcp-server .

Running

Command Line

./mcp-server

The server reads JSON-RPC requests from stdin and writes responses to stdout.

Docker

docker run --rm -i cbl-mcp-server

Testing

Run the test suite to verify all functionality:

# Test with Docker (default)
node test.js

# Or with npm
npm test

# Test with local binary (requires GnuCOBOL installed)
USE_DOCKER=false node test.js

Test Coverage

The test suite verifies:

• ✓ Server startup
• ✓ Initialize request/response
• ✓ Tools list endpoint
• ✓ Tax calculation (multiple amounts)
• ✓ Ping endpoint
• ✓ Error handling (unknown method)

Example output:

═══════════════════════════════════════════════════════
         CBL-MCP-SERVER TEST SUITE
═══════════════════════════════════════════════════════

  Test 1: Server startup
    ✓ Server started successfully

  Test 2: Initialize request
    ✓ Initialize response is valid

  Test 3: Tools list request
    ✓ Tools list response is valid

  Test 4-7: Tax calculations
    ✓ All tax calculations correct

  Test 8: Ping request
    ✓ Ping response is valid

  Test 9: Unknown method error handling
    ✓ Error response is valid

═══════════════════════════════════════════════════════
  Total: 9 | Passed: 9 ✓ | Failed: 0 ✗
═══════════════════════════════════════════════════════

API Reference

Methods

initialize

Initialize the MCP connection.

Request:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

Response:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "protocolVersion":"2025-06-18",
    "capabilities":{"tools":{}},
    "serverInfo":{"name":"cbl-mcp","version":"1.0.0"}
  }
}

tools/list

List available tools.

Request:

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Response:

{
  "jsonrpc":"2.0",
  "id":2,
  "result":{
    "tools":[{
      "name":"calculate_tax",
      "description":"Calculate 7.5 percent sales tax on an amount",
      "inputSchema":{
        "type":"object",
        "properties":{
          "amount":{"type":"number","description":"The pre-tax amount"}
        },
        "required":["amount"]
      }
    }]
  }
}

tools/call

Execute a tool with arguments.

Request:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"calculate_tax","arguments":{"amount":100}}}

Response:

{
  "jsonrpc":"2.0",
  "id":3,
  "result":{
    "content":[{
      "type":"text",
      "text":"Amount 100.00, tax 7.50, total 107.50"
    }]
  }
}

ping

Health check endpoint.

Request:

{"jsonrpc":"2.0","id":6,"method":"ping"}

Response:

{"jsonrpc":"2.0","id":6,"result":{}}

Example Usage

Single Request

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate_tax","arguments":{"amount":500}}}' | ./mcp-server

Multiple Requests

cat << 'EOF' | ./mcp-server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"calculate_tax","arguments":{"amount":100}}}
EOF

With Docker

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate_tax","arguments":{"amount":1000}}}' | docker run --rm -i cbl-mcp-server

Using with LLMs (Claude Desktop, etc.)

This MCP server can be connected to LLM clients that support the Model Context Protocol, allowing natural language interaction.

Claude Desktop Setup

1. Build the Docker image:

   docker build -t cbl-mcp-server .
   

2. Add to Claude Desktop config:

   Edit your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   Add the server configuration:

   {
     "mcpServers": {
       "cbl-mcp-server": {
         "command": "docker",
         "args": ["run", "--rm", "-i", "cbl-mcp-server"]
       }
     }
   }
   

3. Restart Claude Desktop

4. Use natural language:

   You: What's the sales tax on $150?
   
   Claude: I'll calculate the 7.5% sales tax for you.
   [Uses calculate_tax tool]
   The sales tax on $150 is $11.25, making the total $161.25.
   

Local Binary Setup

If you have GnuCOBOL installed locally:

1. Build:

   make
   

2. Configure Claude Desktop:

   {
     "mcpServers": {
       "cbl-mcp-server": {
         "command": "/home/srinivasan/cbl-mcp-server/mcp-server",
         "args": []
       }
     }
   }
   

Example Conversations

Once connected, you can interact naturally:

Example 1 - Tax Calculation:

You: Calculate the sales tax for a $500 purchase

Claude: [Calls calculate_tax tool]
For a $500 purchase with 7.5% sales tax:
- Tax: $37.50
- Total: $537.50

Example 2 - Price Comparison:

You: Which costs more after tax: $99.99 or $100?

Claude: [Calls calculate_tax tool twice]
After 7.5% sales tax:
- $99.99 → $107.48 (tax: $7.49)
- $100.00 → $107.50 (tax: $7.50)

$100 actually costs 2 cents more after tax ($107.50 vs $107.48).

Example 3 - Budget Planning:

You: I have $200 budget. What's the maximum pre-tax price I can afford?

Claude: [Calculates reverse: 200 / 1.075 ≈ 186.05]
With 7.5% tax, $186.05 pre-tax becomes $200.00 total.
Let me verify:
- Pre-tax: $186.05
- Tax (7.5%): $13.95
- Total: $200.00

You can afford items up to $186.05 before tax.

Tax Calculation Details

• Tax Rate: 7.5%
• Precision: 2 decimal places
• Formula:
  • Tax = Amount × 0.075
  • Total = Amount + Tax

Examples

Amount	Tax	Total
$100.00	$7.50	$107.50
$500.00	$37.50	$537.50
$1,000.00	$75.00	$1,075.00
$99.99	$7.49	$107.48
$0.01	$0.00	$0.01

Architecture

Request Flow

stdin → READ-REQUEST → PARSE-REQUEST → DISPATCH-REQUEST → BUILD-*-RESPONSE → WRITE-RESPONSE → stdout

Components

Module	Purpose
server.cbl	Main loop, orchestrates request processing
transport.cbl	Low-level I/O operations (ACCEPT, DISPLAY)
parser.cbl	JSON parsing using UNSTRING
dispatcher.cbl	Method routing via EVALUATE
response-builder.cbl	JSON response construction via STRING
tax-service.cbl	Business logic for tax calculation

Development

Clean Build

make clean && make

Compiler Flags

The Makefile uses these GnuCOBOL flags:

• -free: Free-format source code
• -fnot-reserved=ALL: Don't reserve common words
• -I copybooks: Include copybook directory
• -x: Create executable

Adding New Tools

1. Add tool schema to BUILD-TOOLS-LIST-RESPONSE in response-builder.cbl
2. Add case handler in dispatcher.cbl EVALUATE block
3. Create response builder in response-builder.cbl
4. Implement business logic (e.g., new service file)

License

This project is provided as-is for educational and demonstration purposes.

Contributing

Contributions are welcome! Please ensure all COBOL code follows free-format style and includes appropriate comments.