@xferops/forge-mcp 2.0.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@xferops/forge-mcp",
+  "version": "2.0.0",
+  "description": "MCP server for Forge (XferOps project management) - works with Claude Code, Codex, OpenClaw, and any MCP consumer",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "forge-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "forge",
+    "kanban",
+    "project-management",
+    "claude",
+    "codex",
+    "openclaw",
+    "xferops"
+  ],
+  "author": "XferOps <support@xferops.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XferOps/forge-mcp.git"
+  },
+  "homepage": "https://forge.xferops.dev/docs",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,13 @@
+# Forge Skills
+
+The Forge MCP skill has been split into three focused skills. Use the one that matches your intent:
+
+| Skill | When to use |
+|-------|-------------|
+| [`forge-dev-workflow`](./forge-dev-workflow/SKILL.md) | Picking up tickets, moving them through columns, linking PRs, commenting — the daily dev loop |
+| [`forge-board-admin`](./forge-board-admin/SKILL.md) | Managing projects, columns, and team membership |
+| [`forge-setup`](./forge-setup/SKILL.md) | First-time install and configuration, or when health check fails |
+
+## Why three skills?
+
+Loading 26 tools + docs for every ticket comment is wasteful. Each skill now covers only the tools and workflow guidance relevant to a specific intent, keeping context lean and guidance actionable.

package/skill/forge-board-admin/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: forge-board-admin
+description: Manage Forge projects, columns, and team membership. Use when creating or updating boards, reordering or adding columns, or managing team members. NOT for day-to-day ticket work (use forge-dev-workflow for that).
+---
+
+# Forge — Board Administration
+
+For setting up and maintaining boards, columns, and team membership. This is Parker/Adam territory — dev agents rarely need this.
+
+## Prerequisite
+
+Forge MCP must be configured. If `forge_health_check` fails, run the `forge-setup` skill first.
+
+## Projects
+
+### Create a project
+```
+forge_create_project teamId=<id> name="Project Name" prefix="PRJ"
+```
+`prefix` sets the ticket ID prefix (e.g. `PRJ-1`, `PRJ-2`). Choose something short and unique.
+
+### Update a project
+```
+forge_update_project projectId=<id> name="New Name"
+```
+
+### Delete a project
+```
+forge_delete_project projectId=<id>
+```
+⚠️ Irreversible. All tasks and history are gone.
+
+### List all projects in a team
+```
+forge_list_projects teamId=<id>
+```
+
+### Get a project (with columns + tasks)
+```
+forge_get_project projectId=<id>
+```
+Use this to retrieve column IDs before creating tasks or building automations.
+
+## Columns
+
+Standard XferOps column order:
+**Backlog → Blocked → To Do → In Progress → Code Review → Staging → Ready for Prod → Done**
+
+### Create a column
+```
+forge_create_column projectId=<id> name="Column Name"
+```
+
+### Rename a column
+```
+forge_update_column columnId=<id> name="New Name"
+```
+
+### Reorder columns
+```
+forge_reorder_columns projectId=<id> columnIds=["<id1>","<id2>","<id3>"]
+```
+Pass the full ordered list of column IDs.
+
+### Delete a column
+```
+forge_delete_column columnId=<id>
+```
+⚠️ Move all tasks out first — tasks in a deleted column may be lost.
+
+## Team Members
+
+### List team members
+```
+forge_list_team_members teamId=<id>
+```
+
+### Add a member
+```
+forge_add_team_member teamId=<id> email="user@example.com"
+```
+
+## Tools used by this skill
+
+| Tool | When |
+|------|------|
+| `forge_list_teams` | List all teams in the org |
+| `forge_list_projects` | List projects in a team |
+| `forge_get_project` | Get project details, column IDs, task list |
+| `forge_create_project` | Create a new board |
+| `forge_update_project` | Rename a project |
+| `forge_delete_project` | Delete a project (irreversible) |
+| `forge_create_column` | Add a column to a board |
+| `forge_update_column` | Rename a column |
+| `forge_delete_column` | Remove a column (move tasks first) |
+| `forge_reorder_columns` | Change column order |
+| `forge_list_team_members` | See who's on the team |
+| `forge_add_team_member` | Add a user by email |
+| `forge_health_check` | Verify API connectivity |

package/skill/forge-dev-workflow/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: forge-dev-workflow
+description: Pick up, work, move, and comment on Forge tasks during the dev loop. Use when claiming a ticket, moving it through columns, linking a PR, or adding status comments. NOT for managing projects, columns, or team membership (use forge-board-admin for that).
+---
+
+# Forge — Dev Workflow
+
+The standard loop for development work: find a ticket → claim it → ship code → move it through review → done.
+
+## Prerequisite
+
+Forge MCP must be configured. If `forge_health_check` fails, run the `forge-setup` skill first.
+
+## The Dev Loop
+
+### 1. Find your next ticket
+
+```
+forge_search_tasks query="ADM-12"          # look up a specific ticket
+forge_list_tasks projectId=<id>            # browse a board
+```
+
+Use `forge_get_task` to read full details, description, and existing comments before starting.
+
+### 2. Claim it — move to In Progress
+
+```
+forge_move_task taskId=<id> columnId=<in-progress-col-id>
+```
+
+Always comment when you start:
+```
+forge_create_comment taskId=<id> content="Picking this up now."
+```
+
+### 3. During work — comment on blockers or context
+
+If you hit a blocker, comment immediately and move to Blocked:
+```
+forge_create_comment taskId=<id> content="Blocked: <reason>. Needs input from <person>."
+forge_move_task taskId=<id> columnId=<blocked-col-id>
+```
+
+### 4. PR ready — move to Code Review
+
+```
+forge_move_task taskId=<id> columnId=<code-review-col-id>
+forge_create_comment taskId=<id> content="PR open: <url>. Ready for review."
+```
+
+### 5. Feedback addressed — re-request review
+
+Push fixes, then comment:
+```
+forge_create_comment taskId=<id> content="Addressed review feedback (see PR). Re-requesting review."
+```
+
+### 6. Merged → Staging
+
+After merge and successful staging deploy:
+```
+forge_move_task taskId=<id> columnId=<staging-col-id>
+forge_create_comment taskId=<id> content="Merged and deployed to staging. Test at <url>."
+```
+
+### 7. Staging verified → Ready for Prod
+
+```
+forge_move_task taskId=<id> columnId=<ready-for-prod-col-id>
+```
+
+### 8. Released → Done
+
+```
+forge_move_task taskId=<id> columnId=<done-col-id>
+```
+
+## Column IDs
+
+Column IDs vary by project. Get them with:
+```
+forge_get_project projectId=<id>   # returns columns[] with id + name
+```
+
+Common column names (in order): **Backlog → Blocked → To Do → In Progress → Code Review → Staging → Ready for Prod → Done**
+
+## Assigning tasks
+
+```
+forge_update_task taskId=<id> assigneeId=<userId>
+```
+
+- Assign to yourself when starting
+- Assign to `quinn-xferops-ai` when moving to Staging (QA ownership)
+- Assign to `adam-xferops-ai` when you need a senior unblock
+- Leave unassigned when parking in Backlog
+
+## Task types
+
+- `TASK` — discrete work item
+- `BUG` — something broken
+- `STORY` — larger initiative
+
+## Priority order
+
+Always work: **Critical → High → Medium → Low**
+
+## Tools used by this skill
+
+| Tool | When |
+|------|------|
+| `forge_search_tasks` | Find tickets by title, description, or ID (e.g. "ADM-5") |
+| `forge_list_tasks` | Browse all tasks in a project |
+| `forge_get_task` | Read full task details before starting |
+| `forge_create_task` | Create a ticket for work that doesn't have one |
+| `forge_update_task` | Update fields, assignee, priority, type |
+| `forge_move_task` | Move between columns |
+| `forge_create_comment` | Leave status updates, PR links, blocker notes |
+| `forge_list_comments` | Read existing comments for context |
+| `forge_health_check` | Verify API connectivity |

package/skill/forge-setup/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: forge-setup
+description: Install and configure the Forge MCP server for the first time, or verify an existing setup. Use when forge_health_check fails or when setting up a new agent environment.
+---
+
+# Forge — Setup
+
+One-time installation and configuration of the Forge MCP server.
+
+## Install
+
+```bash
+npx -y @xferops/forge-mcp
+```
+
+## Configure
+
+Add to your MCP client config (e.g. `~/.mcporter/mcporter.json`):
+
+```json
+{
+  "mcpServers": {
+    "forge": {
+      "command": "npx",
+      "args": ["-y", "@xferops/forge-mcp"],
+      "env": {
+        "FORGE_URL": "https://forge.xferops.dev",
+        "FORGE_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Get your API token: **Forge → Settings → API Tokens**
+
+## Verify
+
+```
+forge_health_check
+```
+
+A `200 OK` response means you're connected and authenticated. Any other result:
+- **401** — token is wrong or expired; generate a new one in Forge settings
+- **Connection refused / timeout** — `FORGE_URL` is wrong, or the service is down
+
+## Legacy env vars
+
+If migrating from the old Flower app, `FLOWER_URL` and `FLOWER_TOKEN` are accepted as fallbacks but deprecated. Update to `FORGE_URL` / `FORGE_TOKEN`.
+
+## Tools used by this skill
+
+| Tool | When |
+|------|------|
+| `forge_health_check` | Verify the MCP server can reach the Forge API |