rtc-mcp

MCP server for IBM Rational Team Concert (RTC / EWM).
Works out-of-the-box with IBM Bob — no manual path editing, no environment variables.

What it does

rtc-mcp is a Model Context Protocol server that lets IBM Bob talk directly to your RTC / EWM instance via its OSLC REST API.

Once configured, you can ask Bob things like:

"Create a defect for the blank client view page, owned by Sachin, GA gate, severity Critical"

Bob will call the MCP tool, post the work item to RTC via the OSLC API, and return the new work item ID and a direct link — all without opening the browser.

Available tools

| Tool | What it does | |---|---| | get_work_items | List work items in a project area | | get_work_item | Fetch a single work item by ID | | get_work_item_rdf | Fetch a work item as raw RDF/XML | | create_work_item | Create a Defect, Execution Record, Task, or Story | | update_work_item | Update title / description / status / owner / tags | | get_service_provider | Get the OSLC service provider for a project area | | get_project_areas | List all project areas | | search_work_items | Full-text search across work items | | get_resource_shape | Inspect field shapes for a work item type | | add_attachment | Attach a local file reference to a work item |

Installation

npm install -g rtc-mcp

Requires Node.js 18 or later.

Quick start

# 1. First-time setup
rtc-mcp init

# 2. Verify everything works
rtc-mcp doctor
rtc-mcp test

# 3. Add to Bob
rtc-mcp generate-config
# → paste the output into ~/.bob/settings/mcp.json

# 4. Restart Bob — all RTC tools are now available

Getting your RTC cookies

rtc-mcp authenticates via browser session cookies (no password stored on disk).

1. Open your RTC server in Chrome or Firefox and log in.
2. Press F12 → Application tab → Storage > Cookies → click your RTC hostname.
3. Copy the values of:
   • JSESSIONID
   • LtpaToken2
4. Run rtc-mcp init and paste them when prompted.

Tip: Cookies expire after a browser session ends (typically 8–12 hours). When Bob starts returning auth errors, run rtc-mcp login to refresh them.

CLI reference

rtc-mcp init

Interactive first-time setup. Prompts for:

• RTC server URL
• JSESSIONID
• LtpaToken2
• JazzFormAuth (defaults to Form)

Saves to ~/.rtc-mcp/config.json with permissions 0600.

rtc-mcp login

Refresh the cookies while keeping the existing RTC URL.
Run this whenever Bob reports session-expired errors.

rtc-mcp doctor

Diagnose your setup:

• Checks Node.js version
• Verifies config file exists and is valid
• Pings the RTC server to confirm network access

rtc-mcp test

Calls GET /jazz/oslc/projectareas with your current cookies.
Confirms that authentication is working before you start Bob.

rtc-mcp generate-config

Prints the Bob MCP config block you need to add to ~/.bob/settings/mcp.json:

{
  "mcpServers": {
    "rtc-server": {
      "command": "rtc-mcp",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

No hardcoded paths. No environment variables. Bob launches rtc-mcp as a child process and it reads your config automatically.

Bob configuration

Open ~/.bob/settings/mcp.json and add (or merge) the rtc-server block:

{
  "mcpServers": {
    "rtc-server": {
      "command": "rtc-mcp",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Save the file and restart Bob. The RTC tools will appear in Bob's tool list.

If you installed locally (not globally), use the full path:

"command": "node",
"args": ["/path/to/rtc-mcp/build/index.js"]

Config file

Configuration is stored at ~/.rtc-mcp/config.json:

{
  "rtcUrl": "https://your-rtc-server:9443/",
  "cookies": {
    "JazzFormAuth": "Form",
    "JSESSIONID": "your-session-id",
    "LtpaToken2": "your-ltpa-token"
  }
}

The file is created by rtc-mcp init with 0600 permissions (readable only by you).
Never commit this file to source control.

Updating cookies

When your RTC session expires:

rtc-mcp login

Then restart Bob (the MCP server process must be restarted to load the new cookies).

Troubleshooting

"Configuration not found. Run: rtc-mcp init"

The config file does not exist yet. Run rtc-mcp init.

"RTC session expired. Run: rtc-mcp login"

Your JSESSIONID or LtpaToken2 has expired. Run rtc-mcp login then restart Bob.

Bob does not show RTC tools

1. Confirm disabled is false in ~/.bob/settings/mcp.json.
2. Run rtc-mcp doctor to check the config.
3. Run rtc-mcp test to verify cookies are valid.
4. Restart Bob after any config change.

"command not found: rtc-mcp"

The package is not installed globally. Either:

npm install -g rtc-mcp

or use the full path in mcp.json:

"command": "node",
"args": ["/path/to/rtc-mcp/build/index.js"]

RTC server unreachable

• Check you are connected to the IBM VPN.
• Verify the URL you entered during rtc-mcp init is correct.
• Run rtc-mcp doctor for a connectivity check.

TypeScript build errors (development only)

rm -rf build/
npm run build

Development

# Clone and install
git clone <repo-url>
cd rtc-mcp
npm install

# Build
npm run build

# Watch mode
npm run watch

# Link globally for local testing
npm link
rtc-mcp doctor

Publishing to npm

# Login to npm
npm login

# Dry run — preview what will be published
npm pack --dry-run

# Publish
npm publish --access public

To publish under a scope:

npm publish --access public --scope @your-scope

Update the name field in package.json accordingly before publishing.

Security

• Cookies are stored only in ~/.rtc-mcp/config.json with 0600 permissions.
• The config file is never read from environment variables or command-line arguments.
• Cookies are transmitted only to your RTC server over HTTPS.
• Self-signed certificates on RTC are accepted (common in IBM internal environments).
• Never commit ~/.rtc-mcp/config.json to source control.

License

MIT — see LICENSE.

Made with IBM Bob