# okffs [Health: Active]

**Category:** 🔄 Version Control  
**Repository:** https://github.com/neturely/okffs  
**GitHub Stars:** 2  
**npm Downloads (last month):** 249  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/okffs

## Description
MCP server connecting Claude Code to GitHub for an issue to branch to PR to close workflow.

## Tools
Capabilities this server exposes over MCP:

- **create_issue** — Creates an issue and a matching branch (an **Epic** gets no branch or draft PR — work lands on its children). Infers labels, a board `priority`/`effort`, and a native Issue Type from the task (toggle with `OKFFS_INFER_PRIORITY`/`OKFFS_INFER_EFFORT`/`OKFFS_INFER_TYPE`). Optional `assignees`, `labels…
- **create_issues_from_list** — Creates many issues + branches from a task list in one shot. Confirms first. Per-task `labels`, `assignees`, `milestone`, `priority`, `effort`, `type`.
- **plan** — Give it a free-text description plus the breakdown Claude generates (titles, descriptions, labels, priority/effort/type, relationships); it creates every issue + branch, wires up relationships, and opens draft PRs when `OKFFS_AUTO_PR=true`. Confirms first.
- **list_issues** — Lists open issues with branch, linked PR, board column, `priority:`/`effort:`, native `type:`, and relationships as a tree — ordered by priority so the most important work is on top.
- **get_issue** — Full details for one issue: title, body, labels, assignees, branch, status.
- **comment_issue** — Posts a comment — handy for logging what a branch did.
- **link_issues** — Links two issues (`blocked_by`, `blocking`, `parent`), stored under a `## Relationships` section.
- **close_issue** — Closes an issue and tips you to `/clear` before the next one.
- **create_pull_request** — Opens a PR for an issue branch — generates the title/body, pushes the branch, always includes `Closes #N`, and comments back. Can write changelog fragments when `OKFFS_UPDATE_DOCS=true`. Pass `allow_empty: true` to backfill a **draft** tracking PR on a branch with no commits (pushes an empty init c…
- **commit_and_update** — Stages tracked changes (untracked need `include_untracked: true`), commits (your `message` verbatim, or an auto-generated one), pushes, and posts a progress comment to the issue. Refuses secret-looking files.
- **merge_pull_request** — Autonomously merges a green, review-resolved issue PR into the **base** branch (e.g. `develop`) using `OKFFS_BASE_MERGE_METHOD`, then closes the issue. Opt-in (`OKFFS_AUTO_MERGE_BASE=true`) and heavily gated — never touches `OKFFS_PROTECTED_BRANCH`, independently verifies checks/mergeability/thread…
- **fix_into_base** — Opens (and, under the same `OKFFS_AUTO_MERGE_BASE` gates, merges) an **issue-less** fix PR into the base branch — for small cleanups such as review-comment fixes. Never targets `OKFFS_PROTECTED_BRANCH`.
- **promote_branch** — Opens the issue-less **promotion PR** (e.g. `develop → main`), boards it, optionally requests reviewers, and lists the **releases it carries** per app. A re-run reports unresolved review threads and — when you opt in — **merges** the gate PR (`OKFFS_AUTO_MERGE_PROTECTED`) and **tags** the merged re…
- **list_pr_review_comments** — Fetches a PR's inline review threads and summaries.
- **reply_to_review_comment** — Replies to an inline review thread by id.
- **resolve_review_thread** — Resolves a review thread — only when `OKFFS_RESOLVE_THREADS=true`.
- **prepare_release** — Bumps the version (`package.json`, or a plain `VERSION` file when there is none — created on the first release), rolls the CHANGELOG, commits on a release branch, and opens a PR. Confirms first; does not tag or publish. Per app under [multisite](#multisite-several-apps-in-one-repo).
- **update_project_status** — Moves an issue between board columns (`Backlog`, `Ready`, `In Progress`, `Review`). Needs `OKFFS_PROJECT_ENABLED`.
- **set_issue_fields** — Sets board Priority/Effort **and/or the native Issue Type** on an **existing** issue. Priority/Effort handle project-native and org-level Issue Fields (needs `OKFFS_PROJECT_ENABLED`); `type` is org-native and works independently. `create_issue` only sets these at creation; use this afterwards. Stat…
- **update_issue** — Edits an **existing** issue's core fields — `title`, `assignees`, `labels`, `milestone`, `body` — via one PATCH with the configured token. `labels`/`assignees` replace the whole set (`[]` clears). For Priority/Effort/Type use `set_issue_fields`; for Status use `update_project_status`.
- **configure** — Writes okffs config to `.env` — the backend for the `/okffs:setup` prompt. Reuses the `okffs setup` wizard's manifest/serializer: updates only okffs's marked block, preserving your own variables and comments. `app: "finance"` writes `finance/.env` instead; makes sure `.gitignore` covers `.env` at e…
- **delete_issue** — Closes an issue **and** deletes its branch. Destructive — needs `confirmed: true`.
- **delete_branch** — Deletes a branch **and** closes its issue. Destructive — needs `confirmed: true`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "okffs": {
    "command": "npx",
    "args": ["-y","@neturely/okffs"]
  }
}
```

## Documentation

## What the okffs MCP server does

The okffs MCP server gives Claude Code an MCP interface for coordinating GitHub-based development work. It can turn a task description into issues and matching branches, preserve relationships between issues, and connect those issues to pull requests. An Epic is treated differently: it does not receive its own branch or draft pull request, because implementation is expected to land through child issues.

The workflow covers planning, implementation, review, and release preparation. You can list open work as a priority-ordered tree, inspect or edit issue details, move issues between supported project columns, and set board fields or native issue types. Destructive operations such as deleting an issue or branch require explicit confirmation.

## How it works

Claude Code calls the server's tools over MCP. Planning tools accept a free-text description or task list and can create multiple issues, branches, labels, assignments, milestones, field values, and relationships. When enabled, issue creation can also open draft pull requests.

For implementation work, the server can stage tracked changes, create a commit, push it, and add a progress comment. Pull request creation generates the title and body, includes a closing reference to the issue, pushes the branch, and comments on the issue. Review tools retrieve inline threads, post replies, and optionally resolve threads when the corresponding setting is enabled.

Merge and promotion actions have separate opt-in controls and safety checks. Base-branch merging requires a green, review-resolved pull request and does not target the configured protected branch. Release preparation updates the version and changelog on a release branch, then opens a pull request without tagging or publishing.

## Setup and configuration

Install or run the package through `npx` and register it as a stdio MCP server in the project's `.mcp.json`:

```json
{
  "mcpServers": {
    "okffs": {
      "command": "npx",
      "args": ["@neturely/okffs@latest"]
    }
  }
}
```

From the repository root, `npx @neturely/okffs setup` launches a wizard for authentication, repository selection, and optional features. It writes the okffs section of `.env` and runs a GitHub check. The setup flow can also be started from Claude Code with `/okffs:setup`; its configuration tool preserves unrelated variables and comments. Existing `gh` authentication inside the repository can be used without additional configuration.

Optional settings control inference, project synchronization, automatic pull requests, merge behavior, review-thread resolution, documentation updates, release tagging, and multisite release handling. Project-column and board-field tools require project support to be enabled.

## Tools and capabilities

The available capabilities include:

- Create one issue and branch, many issues from a list, or a complete planned breakdown.
- List and inspect issues, edit core fields, add comments, close work, and link issues as parent, blocking, or blocked by relationships.
- Commit and push changes, create issue pull requests, apply issue-less fixes to the base branch, and promote the base branch toward a protected branch.
- Read pull request review threads, reply to comments, and optionally resolve them.
- Prepare version and changelog changes in a release pull request.
- Update project status, set priority or effort, and assign native issue types.
- Delete an issue with its branch or delete a branch with its issue after confirmation.

The okffs MCP server also includes a configuration tool intended mainly for the setup prompt rather than direct conversational use.

## Limitations and notes

The server operates around GitHub issues, branches, pull requests, and optional GitHub Projects features. It does not publish releases as part of `prepare_release`; that tool prepares and opens the release pull request only. Empty tracking pull requests require `allow_empty: true` and create an initial empty commit so the branch diverges.

Untracked files are excluded from commits unless `include_untracked: true` is supplied, and secret-looking files are refused. Issue labels and assignees supplied to `update_issue` replace the existing sets rather than appending to them. Status changes use `update_project_status`, while priority, effort, and type use `set_issue_fields`.

Automatic merging is disabled unless explicitly enabled and remains gated by branch, check, mergeability, and review conditions. Destructive issue and branch operations require a second confirmed call.

_Full upstream README: https://allmcps.com/mcp/okffs/readme_