# Sitemule Blueprint MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for
IBM i program analysis, built with [FastMCP](https://github.com/jlowin/fastmcp).

> **⚠️ Prerequisite:** This MCP server **requires a licensed copy of
> [Sitemule Blueprint](https://sitemule.com/blueprint)** running on an IBM i
> server. Without it, there is no backend to connect to.
> Contact [Sitemule](https://sitemule.com) for licensing information.

## Features

- **STDIO** and **Streamable HTTP** transports
- IBM i program call-chain analysis (top-down & bottom-up)
- Source code retrieval and regex search
- Configurable API endpoint and API key (key is never exposed to the LLM)
- Packaged for PyPI via `uv`
- Self-contained executables for Windows, macOS, and Linux

## Tools

The MCP server exposes **13 tools** for IBM i program analysis.
Configuration management (`getConfig`, `setConfig`) and graph rebuilds
(`loadGraph`) are handled by the companion **VS Code extension** — see
[VS Code Extension](#vs-code-extension) below.

### Read-only

| Tool | Description |
|------|-------------|
| `list_nodes` | List nodes from the Blueprint graph, optionally filtered by name, type, or ID |
| `topdown` | Get all programs recursively used by a given program (top-down call chain) |
| `topdown_prompt` | Top-down call chain with descriptions and source intro for each node |
| `bottomup` | See where a program is called from (bottom-up / reverse call chain) |
| `prompt` | Get descriptions and source-code intro for a program and its call chain |
| `load_source` | Get full source code and metadata for a program or table |
| `search_source` | Search the source repository for text matching a regular expression |
| `list_errors` | List entries from the Blueprint error log |
| `get_domains` | Get all defined domains |
| `get_markdown` | Get Markdown documentation for a program or node |
| `get_html` | Get HTML documentation for a program or node |

### Mutation (require user approval)

| Tool | Annotation | Description |
|------|------------|-------------|
| `set_domain` | destructive | Assign a domain to a node |
| `create_domain` | additive | Create a new domain node |

## Installation

### From PyPI

```bash
# Install with uv
uv pip install blueprint-mcp

# Or with pip
pip install blueprint-mcp
```

### From source

```bash
cd src/python/blueprint-mcp
uv sync
```

## VS Code Extension

The companion **Sitemule Blueprint** extension (in `vscode-extension/`)
provides a Settings UI and manages server communication directly:

| Command | Description |
|---------|-------------|
| **Blueprint: Refresh Settings from Server** | Fetch current config via `getConfig` and populate VS Code settings |
| **Blueprint: Save Settings to Server** | Push VS Code settings to the backend via `setConfig` |
| **Blueprint: Rebuild Dependency Graph** | Trigger `loadGraph` to re-scan the IBM i |
| **Blueprint: Save Settings & Rebuild Graph** | Save config then rebuild in one step |
| **Blueprint: Generate mcp.json** | Write `.vscode/mcp.json` to register the MCP server |

**Workflow:**
1. Set `blueprint.apiUrl` (and optionally `blueprint.apiKey`) in VS Code settings
2. The extension fetches the current config from the backend on activation
3. Edit any setting — changes are automatically pushed to the backend
4. Use the command palette to rebuild the graph when ready

The extension also generates `.vscode/mcp.json` automatically so VS Code
can launch the MCP server with the correct API credentials.

## Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BLUEPRINT_API_URL` | Yes | `http://MY_IBM_I:60111/services/api` | Base URL for the Blueprint API |
| `BLUEPRINT_API_KEY` | No | _(none)_ | API key sent as `Authorization: Bearer <key>` header. **Never exposed to the LLM.** |
| `BLUEPRINT_HOST` | No | `0.0.0.0` | Host for HTTP transport |
| `BLUEPRINT_PORT` | No | `8000` | Port for HTTP transport |

## Usage

### STDIO (default — for IDE integrations like VS Code, Cursor, etc.)

```bash
BLUEPRINT_API_URL=http://ibm-i.host.or.ip:60111/services/api blueprint-mcp
```

### Streamable HTTP

```bash
BLUEPRINT_API_URL=http://ibm-i.host.or.ip:60111/services/api blueprint-mcp --transport streamable-http
```

### With API key

```bash
BLUEPRINT_API_URL=http://ibm-i.host.or.ip:60111/services/api \
BLUEPRINT_API_KEY=my-secret-key \
blueprint-mcp --transport streamable-http --port 9000
```

### MCP client configuration (e.g. Claude Desktop, VS Code)

```json
{
  "mcpServers": {
    "blueprint": {
      "command": "blueprint-mcp",
      "env": {
        "BLUEPRINT_API_URL": "http://ibm-i.host.or.ip:60111/services/api",
        "BLUEPRINT_API_KEY": "my-secret-key"
      }
    }
  }
}
```

### VS Code — one-click install from MCP Registry

1. Open the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
2. Run **MCP: Add Server…** → search for **Sitemule Blueprint**
3. VS Code will prompt you for the API URL and (optionally) the API key
4. Settings are stored securely — the API key is never exposed to the LLM

Or add a `.vscode/mcp.json` file to your workspace manually:

```json
{
  "inputs": [
    {
      "id": "blueprint-api-url",
      "type": "promptString",
      "description": "Blueprint API URL (e.g., http://ibm-i.host.or.ip:60111/services/api)",
      "default": "http://ibm-i.host.or.ip:60111/services/api"
    },
    {
      "id": "blueprint-api-key",
      "type": "promptString",
      "description": "Blueprint API Key (leave empty if not required)",
      "default": "",
      "password": true
    }
  ],
  "servers": {
    "blueprint": {
      "type": "stdio",
      "command": "blueprint-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "BLUEPRINT_API_URL": "${input:blueprint-api-url}",
        "BLUEPRINT_API_KEY": "${input:blueprint-api-key}"
      }
    }
  }
}
```

### Self-contained executable

Download the pre-built executable for your platform from
[Releases](https://github.com/sitemule/blueprint-mcp/releases) and run it
directly — no Python installation required:

```bash
# Linux / macOS
chmod +x blueprint-mcp-linux
BLUEPRINT_API_URL=http://ibm-i.host.or.ip:60111/services/api ./blueprint-mcp-linux

# Windows
set BLUEPRINT_API_URL=http://ibm-i.host.or.ip:60111/services/api
blueprint-mcp-windows.exe
```

## Building

### Package (for PyPI)

```bash
cd src/python/blueprint-mcp
uv build
# Output: dist/blueprint_mcp-<version>.tar.gz + .whl
```

### Self-contained executable (current platform)

```bash
cd src/python/blueprint-mcp
uv sync --dev
uv run python build_executables.py
# Output: dist/blueprint-mcp-{linux|macos|windows}
```

### All platforms via CI

Push a tag `v*` to trigger the GitHub Actions workflow, which builds
executables for all 3 platforms and publishes to PyPI.

## Development

```bash
cd src/python/blueprint-mcp
uv sync --dev
uv run pytest
```

## License

This software is proprietary and confidential. Copyright (c) 2025 Sitemule. All rights reserved.

A valid commercial license from [Sitemule](https://sitemule.com) is required for any use. See the [LICENSE](LICENSE) file for details.
