Metadata-Version: 2.1
Name: forge-manager-mcp
Home-page: https://codeberg.org/telejester-skills/telejester-claude-skills
License: Apache-2.0
Description-Content-Type: text/markdown
Summary: MCP server for the forge-manager skill — multi-platform forge operations layer (GitHub / Forgejo+Codeberg / GitLab / local docs store)
Project-URL: Changelog, https://codeberg.org/telejester-skills/telejester-claude-skills/src/branch/main/CHANGELOG.md
Project-URL: Homepage, https://codeberg.org/telejester-skills/telejester-claude-skills
Project-URL: Issues, https://codeberg.org/telejester-skills/telejester-claude-skills/issues
Project-URL: Repository, https://codeberg.org/telejester-skills/telejester-claude-skills
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: release
Requires-Dist: Pillow>=10.0; extra == 'release'
Version: 4.18.0a30

# claude-skills-mcp-dev

Private dev repo for the
[`active-claude-github`](https://codeberg.org/telejester-skills/telejester-claude-skills)
Claude Code skill's MCP server. Consumer docs live at the publish
target: <https://codeberg.org/telejester-skills/telejester-claude-skills>.

This repo is where MCP server development happens — Issues,
Discussions, CI, Bazel build graph, tests. Releases are published to
the publish-target repo linked above.

## What lives here

- **Python package** `active_claude_github_mcp/` implementing the MCP
  tool surface.
- **`tests/`** — Bazel-orchestrated unit and integration tests in two
  layers: helper-level (#79, ephemeral repos) and tool-level (#89,
  persistent fixture repo at `telejester-test-org/integration-fixture`).
  See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the build and test
  conventions and §Persistent fixture repo for the provisioning
  protocol.
- **`.github/workflows/`** — CI (`bazel test` + `bazel coverage` on
  every PR; `workflow_dispatch` live-GitHub integration tests).
- **Issues / Discussions / Project board** cross-referenced with the
  skill dev repo at
  <https://github.com/orgs/telejester-claude-skills/projects/1>.

## Bootstrapping a new project

`scaffold_project` is the MCP tool that stands up a new managed project
end-to-end: creates the `<org>/<name>` public + `<org>/<name>-dev`
private repo pair, seeds the standard label set, enables Discussions on
the dev repo, creates a ProjectV2 board (linked to both repos) with the
canonical `Backlog → In Progress → In Review → Done / Parked` Status
field, seeds the Project and Session-Lock Discussions, and writes
`.claude/github-config.json` with every resolved ID.

The tool is idempotent and pauses for exactly one manual step: creating
the five Discussion categories (`Project`, `Architecture`, `UX / UI`,
`Ideas`, `claude-use-only`) via the dev-repo's Settings page, which
GitHub exposes no API for. Re-run the tool once the categories exist
and it picks up where it left off.

The exact bootstrap flow — invocation, expected pauses, and follow-up
`open_session` — lives in the consumer skill's §Self-Bootstrap
Instructions: <https://codeberg.org/telejester-skills/telejester-claude-skills>.

## Multi-repo relations (1.3.0+)

`github-config.json` accepts a `related_repos` list that tags each
connected repo with one of six relationship types. The server uses
these tags at dispatch time to gate cross-repo mutations per the
skill's §Cross-repo work protocol:

| Type | Gate |
|---|---|
| `subsystem`, `publish_target`, `sibling`, `neighbor` | Allowed |
| `cousin` (different org, skill-managed) | **Blocked — requires explicit user permission per operation** |
| `foreign` (no write access) | **Blocked — treat as informational only** |

Blocks surface as a non-buffered `OperationError` with `manual_step`
populated; no GitHub calls are issued. Unknown targets (not declared
in `related_repos`) pass through — the preflight doesn't invent
policy for undeclared repos.

The pre-1.3.0 `contribution_target` type still parses for backward
compat but emits a `DeprecationWarning` at load. Migrate each entry
to its precise sub-type at next config edit.

## Operating system support

Recorded 2026-09-11 (issue #3736), superseding the 2026-09-08 narrowing
(issue #3667).

The package declares `Operating System :: OS Independent` **as a best-effort
claim, by operator decision, and deliberately without a runner behind it.**
Linux is the only OS anything here runs on. For every other OS the claim is an
intention backed by some code, not a measurement.

| OS | Status | What that means |
|---|---|---|
| **Linux** | **Tested** | The suite runs here, and procfs, POSIX signals and the `.claude/scripts/` shell tooling all assume it. |
| **macOS** | **Best-effort, untested** | Real per-OS work exists — `daemon/paths.py` branches on `darwin` for `~/Library/Application Support` and `~/Library/Logs`. Breakage is a bug worth filing, not a promise of a fix in any given release. |
| **Windows** | **Best-effort, untested** | Some guards exist — `preferred_port.py` and `daemon_client.py` check `win32` — and nothing has been run. The `.claude/scripts/` tooling needs WSL or git-bash. |

**Why this changed twice.** Before #3667 the package claimed `OS Independent`
and nothing said the claim was unmeasured. #3667 narrowed it to Linux plus
best-effort macOS, and paired the macOS classifier with a CI job so the claim
would have a runner. #3738 then established that no CI can run for this project
at all, which left that job authored and never executed: a runner in name
only. #3736 resolved it the other way. Every OS is claimed at best-effort, and
this section says plainly that only Linux is exercised. What #3667 filed was a
claim nobody qualified; this section is the qualification.

**What is known to degrade off Linux.** The package reads `/proc` in 8 modules.
Every read site is wrapped in a handler, so nothing crashes; the risk is the
opposite one. Where procfs is absent:

- **Daemon liveness** now reports `unknown` rather than a state. The classifier
  used to answer `busy` — "alive, not stuck, no restart needed" — from
  proc-state samples that were all `None` because the file does not exist. It
  said "D not sustained" about a process nobody had looked at, and a genuinely
  wedged daemon would have read `busy` forever. A classifier that cannot read
  its evidence must say so.
- **Zombie detection is blind.** `is_pid_zombie` returns `False` when it cannot
  read `/proc/<pid>/status`, so a dead-but-unreaped daemon reads as alive.
  This is why the `unknown` verdict says `pid alive` is weaker off Linux.
- **The `.claude/scripts/` tooling** (24 shell scripts, two using `ionice`,
  which macOS does not have) is developer-facing and unaffected by installing
  the package.

The macOS CI job in `.github/workflows/bazel-test.yml` is **authored and has
never run**. It no longer backs a classifier; it is kept so that a runner, if
one is ever provisioned, has a job to execute. Until something runs off Linux,
every row but the first records an intention, not a measurement.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Related repos

- MCP server publish target (consumer-facing):
  <https://codeberg.org/telejester-skills/telejester-claude-skills>
- Skill (consumer-facing):
  <https://codeberg.org/telejester-skills/telejester-claude-skills>
- Skill dev repo:
  <https://codeberg.org/telejester-skills/telejester-claude-skills-dev>

## License

[Apache License 2.0](LICENSE) — © 2026 Telejester.

