tdoms-mcp 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TD/OMS MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# TD/OMS MCP
+
+Standalone TD/OMS change-management MCP for IBM Bob, Codex, Claude-compatible clients, and other agents that can launch a local stdio MCP server. It talks directly to TD/OMS REST APIs and does not require or control the Octo VS Code extension.
+
+This is an independent community project. It is not affiliated with, maintained by, or endorsed by Remain Software, IBM, or their affiliates. TD/OMS, Octo, IBM, IBM i, and IBM Bob are trademarks of their respective owners.
+
+## Setup
+
+Install the published command-line package:
+
+```shell
+npm install --global tdoms-mcp
+tdoms-mcp ui
+```
+
+Or run it from a source checkout:
+
+```powershell
+npm install
+npm run ui
+```
+
+Open `http://127.0.0.1:3737`, add the TD/OMS connection, and test it. Credentials and tokens stay in the local TD/OMS MCP data directory and are never returned to agents.
+
+The Agent setup view detects supported MCP clients and can install or update this server after confirmation. Known configuration files are backed up before each change and restored automatically when a client command fails.
+
+Keep TLS verification enabled. Publicly trusted certificates work without configuration. For an internal certificate authority, set the optional CA certificate file in the connection manager or set `TDOMS_MCP_CA_FILE` to an approved PEM file supplied by the organization.
+
+Start the compact agent-neutral profile:
+
+```powershell
+npm run mcp
+```
+
+Start the complete named-tool profile:
+
+```powershell
+npm run mcp:full
+```
+
+The equivalent environment setting is `TDOMS_MCP_PROFILE=core` or `TDOMS_MCP_PROFILE=full`. `core` is the default.
+
+## Agent Configuration
+
+Use the same local stdio definition in Bob and JSON-based MCP clients after a global npm installation:
+
+```json
+{
+  "command": "tdoms-mcp",
+  "args": ["mcp"],
+  "env": {
+    "TDOMS_MCP_PROFILE": "core"
+  }
+}
+```
+
+Codex TOML:
+
+```toml
+[mcp_servers.tdoms]
+command = "tdoms-mcp"
+args = ["mcp"]
+env = { TDOMS_MCP_PROFILE = "core" }
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+```
+
+Restart or reload the agent's MCP servers after changing the configuration.
+
+Detect supported local clients from the command line:
+
+```powershell
+npm run clients
+```
+
+Install or update one detected client:
+
+```powershell
+node src/index.js install-client ibm-bob --confirm
+node src/index.js install-client codex --confirm
+node src/index.js install-client claude-code --confirm
+node src/index.js install-client vscode --confirm
+```
+
+Configure every detected client that is not already configured:
+
+```powershell
+npm run clients:install
+```
+
+Documented adapters are included for IBM Bob, Codex, Claude Code sessions, Claude Desktop chat, VS Code, Cursor, Windsurf, Kiro, Gemini CLI, Zed, and OpenCode. Microsoft Store Claude installations use the app's virtualized configuration directory automatically.
+
+IBM Bob uses its own global MCP store at `~/.bob/settings/mcp.json`; it does not use VS Code's user-level `mcp.json`. The installer preserves servers from Bob's older `~/.bob/settings/mcp_settings.json` file when creating the current configuration. Bob hot-reloads MCP changes when a workspace folder is open; manage the resulting servers from the MCP tab in the Bob panel settings menu.
+
+Detection and installation are environment-local. Running the installer on Windows configures Windows agents; running it inside WSL configures only that WSL distribution; running it on macOS or Linux uses that platform's native paths. This prevents a Windows client from receiving an unusable WSL command, or the reverse. Claude has two targets: **Claude Code sessions** configures Code sessions opened from Claude Desktop or VS Code, while **Claude Desktop chat** configures regular Desktop chats.
+
+Client installation never copies TD/OMS passwords or tokens into agent configuration. It registers only the local stdio command and the `core` tool profile. Existing files are backed up, writes are atomic, invalid JSON is rejected, and failed client updates are restored.
+
+## Core Workflow
+
+The default profile exposes seven tools:
+
+- `tdoms_list_connections`
+- `tdoms_get_current_context`
+- `tdoms_list_capabilities`
+- `tdoms_discover_options`
+- `tdoms_plan_workflow`
+- `tdoms_execute_workflow`
+- `tdoms_get_workflow_status`
+
+Call `tdoms_get_current_context` first. When one connection exists, it is selected automatically and the saved TD/OMS username becomes the default programmer ID. Octo sign-in context is not required.
+
+Use `tdoms_discover_options` for both site-specific choices and structured reads. It supports workflow choices such as environments, programmers, paths, transfer targets, templates, reasons, conflicts, and user options. It also replaces extension views with task, request, component, source, queue, compile, history, log, spool, tracker, dependency, and dashboard reads. Task reads default to the current programmer; pass `context.allUsers: true` only when a broader search is intended.
+
+For a mutation:
+
+1. Discover the valid choices.
+2. Call `tdoms_plan_workflow` with the chosen context, exact request body, and `optionSelections` keyed by option-set name. Those choices are validated now and before execution.
+3. Review its endpoint/body preview and obtain user approval.
+4. Call `tdoms_execute_workflow` with the returned `planId` and `confirm: true`.
+5. Call `tdoms_get_workflow_status` when the operation is asynchronous.
+
+Plans expire after ten minutes. Execution re-reads relevant TD/OMS state and rejects stale plans. A plan can execute only once.
+
+## Full Profile
+
+The `full` profile exposes 226 tools: the seven universal tools plus the existing task, request, solution, source, object, connection-list, compile, transfer, checkout, promote, branch, spool, log, remote-job, comment, label, user-option, analysis, dashboard, tracker, and administration tools.
+
+All tools that can change TD/OMS require explicit confirmation. `tdoms_call_api` remains available in `full` as an advanced escape hatch for documented endpoints.
+
+## Validation
+
+```powershell
+npm test
+npm run smoke
+```
+
+Tests use mocked TD/OMS clients and do not mutate a real environment. Live mutation tests must be enabled deliberately against a dedicated test system.
+
+Local profiles are stored under `%APPDATA%/tdoms-mcp` on Windows, `~/Library/Application Support/tdoms-mcp` on macOS, and `~/.config/tdoms-mcp` on Linux. Override this with `TDOMS_MCP_DATA_DIR`.
+
+## Credential Storage
+
+Connection metadata is stored in `connections.json`. Passwords and refreshed JWTs are encrypted with AES-256-GCM in `secrets.json`. By default, a random key is stored in `local.key`. All three files use atomic replacement and cross-process locking, and POSIX systems enforce `0700` on the directory and `0600` on files.
+
+For stronger key separation, set `TDOMS_MCP_MASTER_KEY` to 32 random bytes encoded as base64 or 64 hexadecimal characters before adding connections. Keep the same value available to every MCP process that uses that data directory. Changing or losing it makes existing encrypted secrets unreadable.
+
+Generate a base64 key:
+
+```shell
+node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
+```
+
+On Windows, restrict an existing data directory to the current user, SYSTEM, and local Administrators:
+
+```powershell
+npm run secure-storage
+```
+
+Native WSL uses its own Linux data directory and requires Node.js 18 or newer. To reuse the Windows installation and Windows credentials from WSL, launch Windows `node.exe`; otherwise configure the connection separately inside WSL. Avoid sharing credential files through `/mnt/c` unless the Windows ACL has been hardened.
+
+## License
+
+Released under the MIT License. See `LICENSE`.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "tdoms-mcp",
+  "version": "0.6.1",
+  "description": "Agent-neutral MCP server for TD/OMS change-management workflows.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashishthomas2202/tdoms-mcp.git"
+  },
+  "homepage": "https://github.com/ashishthomas2202/tdoms-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ashishthomas2202/tdoms-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tdoms",
+    "change-management",
+    "ibm-i"
+  ],
+  "files": [
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "tdoms-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "mcp": "node src/index.js mcp",
+    "mcp:full": "node src/index.js mcp --profile full",
+    "ui": "node src/index.js ui",
+    "dev": "node src/index.js dev",
+    "smoke": "node src/index.js smoke",
+    "secure-storage": "node src/index.js secure-storage",
+    "clients": "node src/index.js clients",
+    "clients:install": "node src/index.js install-detected --confirm",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.2",
+    "express": "^4.19.2",
+    "jsonc-parser": "^3.3.1",
+    "lucide-static": "^1.24.0",
+    "zod": "^4.1.12"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/tdoms-mcp-routing/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: tdoms-mcp-routing
+description: Use TD/OMS change management through the standalone TD/OMS MCP or Octo MCP tools. Trigger for tasks, requests, source, objects, checkout, promote, transfer, compile, branches, connection lists, logs, spool files, conflicts, labels, and other TD/OMS workflows, especially when an agent incorrectly asks for Octo sign-in or a programmer ID.
+---
+
+# TD/OMS MCP Routing
+
+Prefer the standalone TD/OMS MCP when available. It works independently of the Octo VS Code UI.
+
+## Standalone Core Flow
+
+1. Call `tdoms_get_current_context`. Let it select the only connection and derive the TD/OMS programmer ID from the saved profile.
+2. Call `tdoms_list_capabilities` when the requested workflow or required choices are unclear.
+3. Call `tdoms_discover_options` before choosing application, environment, programmer, path, reason, target, object, template, conflict resolution, or any site-specific value.
+4. Use `tdoms_discover_options` for structured task, request, component, source, queue, compile, history, log, spool, tracker, dependency, and dashboard reads.
+5. For changes, call `tdoms_plan_workflow` with the exact context, selections, and `optionSelections` for values returned by discovery. Show the user its action, target, endpoint/body preview, warnings, and blockers.
+6. Call `tdoms_execute_workflow` with the returned `planId` and `confirm: true` only after the user approves that exact preview.
+7. Call `tdoms_get_workflow_status` for asynchronous work.
+
+Never guess a value when discovery returns no choices or `supported: false`. Ask one concise question instead.
+
+For "my tasks," use option set `tasks` without supplying a programmer. The MCP uses the saved TD/OMS username automatically. Set `context.allUsers: true` only when the user requests tasks for everyone.
+
+## Mutation Rules
+
+- Read current state before planning.
+- Treat source saves, checkout, promote, transfer, compile, complete, delete, process, queue, release, close, and configuration changes as mutations.
+- Never set `confirm: true` without explicit approval of the current plan.
+- Stop when TD/OMS reports warnings, locks, conflicts, authority failures, or changed state. Summarize the result and replan if needed.
+- Never ask the user to paste TD/OMS credentials into chat.
+
+## Full Profile
+
+When `TDOMS_MCP_PROFILE=full`, prefer a specific named read tool when it is clearer than generic discovery. Named mutation tools still require explicit approval and `confirm: true`.
+
+Use typed transfer tools in this sequence: select targets, prepare, inspect warnings, execute, then monitor progress. Use typed source tools to read the latest source and last-change marker before saving. Use compile-and-check to retrieve diagnostics instead of asking the user to paste spool output.
+
+## Octo MCP Fallback
+
+If only the extension MCP is available:
+
+- Use `OMS-Database-REST-API.getRecords` for reads and task lists.
+- Use `TD-OMS-Task-API` only for task mutations.
+- Use `TD-OMS-Branch-Service-API` for branch mutations.
+- Treat `Octo-Views` and `Octo-Wizards` as UI launchers, not proof that an action completed.
+- Do not require `Octo-User-Context` before direct TD/OMS reads.
+
+If Octo user context says sign-in is required but a direct TD/OMS read succeeds, continue with the direct tool and report that the Octo UI context is stale. Retry programmer filters in uppercase before reporting that no tasks exist.

package/skills/tdoms-mcp-routing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TD/OMS MCP Routing"
+  short_description: "Route TD/OMS change-management workflows"
+  default_prompt: "Use $tdoms-mcp-routing to handle this TD/OMS request safely through MCP."

package/src/capability-registry.js

@@ -0,0 +1,124 @@
+export const OPTION_SETS = [
+  "applications",
+  "environments",
+  "programmers",
+  "userClasses",
+  "taskStatuses",
+  "taskTypes",
+  "releases",
+  "priorities",
+  "branchesPaths",
+  "taskObjects",
+  "solutions",
+  "transferTargets",
+  "subEnvironments",
+  "completionReasons",
+  "ratificationReasons",
+  "memberAttributes",
+  "solutionTypes",
+  "compileOverrides",
+  "labels",
+  "objectTemplates",
+  "objectLocations",
+  "revisions",
+  "conflicts",
+  "remoteJobs",
+  "schedules",
+  "trackerLinks",
+  "userOptions",
+  "tasks",
+  "requests",
+  "components",
+  "connectionLists",
+  "buildQueue",
+  "compileResults",
+  "transferHistory",
+  "logs",
+  "spoolFiles",
+  "trackerRecords",
+  "source",
+  "dependencies",
+  "dashboards"
+];
+
+const capabilities = [
+  mutation("change-member-attribute", "Change Member Attribute", "openChangeMemberAttributeWizard", "OMQROB", "/change", ["memberAttributes"], ["applicationCode", "objectCode", "memberCode"], "OMXObjectDetailExtended"),
+  mutation("change-programmer", "Change Programmer", "openChangeProgrammerWizard", "OMQRTA", "/change", ["programmers", "userClasses"], ["applicationCode", "taskNumber"], "OMXFixExtended"),
+  mutation("change-solution-type", "Change Solution Type", "openChangeSolutionTypeWizard", "OMQRSO", "/change", ["solutions", "solutionTypes"], ["applicationCode", "taskNumber"], "OMXSolutionExtended"),
+  mutation("change-task-transfer-path", "Change Task Transfer Path", "openChangeTaskTransferPathWizard", "OMQRTA", "/change", ["branchesPaths"], ["applicationCode", "taskNumber"], "OMXFixExtended"),
+  mutation("compile-override", "Compile Override", "openCompileOverrideWizard", "OMQRCO", "/change", ["compileOverrides", "taskObjects"], ["applicationCode", "taskNumber"], "OMXCompileOverrideExtended"),
+  mutation("complete-task", "Complete Task", "openCompleteTaskWizard", "OMQRTA", "/complete", ["completionReasons"], ["applicationCode", "taskNumber"], "OMXFixExtended"),
+  mutation("delete-objects", "Delete Objects", "openDeleteObjectsWizard", "OMQROB", "/delete", ["taskObjects"], ["applicationCode"], "OMXObjectExtended"),
+  mutation("disconnect-solutions", "Disconnect Solutions", "openDisconnectSolutionsWizard", "OMQRSO", "/disconnect", ["solutions"], ["applicationCode", "taskNumber"], "OMXSolutionExtended"),
+  readOnly("display-message", "Display TD/OMS Message", "openDisplayMessageWizard", [], [], undefined, "Messages are returned directly in MCP responses; no UI window is required."),
+  mutation("edit-branch", "Edit Branch", "openEditBranchWizard", "OMQRBR", "/change", ["branchesPaths"], ["applicationCode", "pathCode"], "OMXTransferPath"),
+  mutation("fill-object-file", "Fill Object File", "openFillObjectFileWizard", "OMQRFO", "/fillObject", ["taskObjects"], ["applicationCode", "objectCode"], "OMXObjectExtended"),
+  mutation("manage-label", "Manage Label", "openLabelWizard", "OMQRLB", "/label", ["labels"], ["applicationCode"], "OMXLabel"),
+  mutation("link-issue-to-task", "Link Issue To Task", "openLinkIssueToTaskWizard", "OMQRTA", "/link/ticket", ["trackerLinks"], ["applicationCode", "taskNumber"], "OMXRemoteIssueInformation"),
+  mutation("link-task-to-issue", "Link Task To Issue", "openLinkTaskToIssueWizard", "OMQRTA", "/link/ticket", ["trackerLinks"], ["applicationCode", "taskNumber"], "OMXRemoteIssueInformation"),
+  mutation("move-solutions", "Move Solutions", "openMoveSolutionsWizard", "OMQRSO", "/move", ["solutions", "branchesPaths"], ["applicationCode", "taskNumber"], "OMXSolutionExtended"),
+  mutation("new-object", "New Object From Template", "openNewObjectTemplatesWizard", "OMQRNO", "/add", ["objectTemplates", "objectLocations"], ["applicationCode", "taskNumber", "environmentCode"], "OMXObjectExtended"),
+  mutation("new-task-branch", "New Task Branch", "openNewTaskBranchWizard", "OMQRBR", "/add", ["branchesPaths"], ["applicationCode", "taskNumber"], "OMXTransferPath"),
+  mutation("close-remote-job", "Close Remote Job", "openCloseRemoteJobWizard", "OMQRRJ", "/close", ["remoteJobs", "completionReasons"], ["applicationCode"], "OMXRemoteJobMonitorExtended"),
+  mutation("reopen-remote-job", "Reopen Remote Job", "openReopenRemoteJobWizard", "OMQRRJ", "/reopen", ["remoteJobs"], ["applicationCode"], "OMXRemoteJobMonitorExtended"),
+  mutation("schedule-remote-job", "Schedule Remote Job", "openScheduleRemoteJobWizard", "OMQRMD", "/schedule", ["remoteJobs", "schedules"], ["applicationCode"], "OMXRemoteJobMonitorExtended"),
+  readOnly("revision-compare", "Revision Compare", "openRevisionCompareWizard", ["revisions"], ["applicationCode"], "OMXObjectTransferHistory"),
+  readOnly("solution-conflict", "Solution Conflict", "openSolutionConflictWizard", ["solutions", "conflicts"], ["applicationCode", "taskNumber"], "OMXObjectVersionConflict", "Conflict resolution is site-specific; discovery is supported and mutation requires a documented site endpoint."),
+  mutation("task-ratification", "Task Ratification", "openTaskRatificationWizard", "OMQRTA", "/ratify", ["ratificationReasons", "programmers"], ["applicationCode", "taskNumber"], "OMXFixExtended"),
+  unsupported("tracker-server-manager", "Tracker Server Manager", "openTrackerServerManagerWizard", "Tracker server administration belongs to Octo configuration and has no known TD/OMS REST endpoint."),
+  mutation("transfer", "Transfer, Checkout, Or Promote", "openTransferWizard", "OMQRTO", "/prepare", ["taskObjects", "transferTargets", "subEnvironments"], ["applicationCode", "taskNumber"], "OMXSolutionExtended"),
+  mutation("unlink-task-from-issue", "Unlink Task From Issue", "openUnlinkTaskFromIssueWizard", "OMQRTA", "/unlink/ticket", ["trackerLinks"], ["applicationCode", "taskNumber"], "OMXRemoteIssueInformation"),
+  mutation("execute-user-option", "Execute User Option", "openUserOptionWizard", "OMQRUO", "/execute", ["userOptions"], ["applicationCode", "taskNumber"], "OMXUserOption"),
+  mutation("resolve-version-conflict", "Resolve Version Conflict", "openVersionConflictsWizard", "OMQRVC", "/confirm", ["conflicts"], ["applicationCode", "taskNumber"], "OMXObjectVersionConflict")
+];
+
+export const CAPABILITIES = Object.freeze(capabilities.map((capability) => Object.freeze(capability)));
+export const CAPABILITY_IDS = CAPABILITIES.map((capability) => capability.id);
+
+export function getCapability(id) {
+  return CAPABILITIES.find((capability) => capability.id === id);
+}
+
+function mutation(id, title, octoWizard, service, path, optionSets, requiredContext, stateTable) {
+  return {
+    id,
+    title,
+    octoWizard,
+    category: "change-management",
+    support: "supported",
+    mode: "mutation",
+    optionSets,
+    requiredContext,
+    stateTable,
+    execution: { method: "POST", service, path }
+  };
+}
+
+function readOnly(id, title, octoWizard, optionSets, requiredContext, stateTable, note) {
+  return {
+    id,
+    title,
+    octoWizard,
+    category: "change-management",
+    support: "supported",
+    mode: "read-only",
+    optionSets,
+    requiredContext,
+    stateTable,
+    note
+  };
+}
+
+function unsupported(id, title, octoWizard, note) {
+  return {
+    id,
+    title,
+    octoWizard,
+    category: "octo-only",
+    support: "unsupported",
+    mode: "read-only",
+    optionSets: [],
+    requiredContext: [],
+    note
+  };
+}