ldraney/forgejo-mcp

Fork 0

DORA query tools for agent reasoning #28

New issue

Closed

opened 2026-06-13 18:34:37 +00:00 by ldraney · 3 comments

ldraney commented

2026-06-13 18:34:37 +00:00

Owner

Type

Feature

Lineage

New issue — created as part of DORA measurement expansion (2026-06-13). Agent DORA expansion line in the DORA framework measurement automation roadmap.

Repo

ldraney/forgejo-mcp

User Story

As an AI agent
I want to query PR velocity, lead time, and rework rate from Forgejo
So that I can reason about DORA metrics and make data-driven recommendations

Context

This is the "Agent DORA expansion" line in the DORA framework measurement automation roadmap. PR merge frequency and lead time are derivable from Forgejo's existing PR data. Rework rate can be approximated from review cycle count.

Agents currently have no way to reason about DORA data. Adding query tools lets agents correlate Forgejo activity with DORA metrics, enabling data-driven decisions about code quality, deployment cadence, and process improvements.

File Targets

src/forgejo_mcp/tools/dora.py — new tool module for DORA query tools
src/forgejo_mcp/tools/__init__.py — register new module via register_all_tools() (add from . import dora import)
tests/test_dora_tools.py — tests for new tools

Feature Flag

None required — new MCP tools are additive.

Acceptance Criteria

At minimum one new MCP tool that queries PR merge frequency and lead time for a given repo over a time range
Returns structured data agents can reason about
Tool handles pagination for repos with many PRs
Time range parameter with sensible defaults (e.g., last 30 days)

Test Expectations

Unit test: tool returns correct PR velocity for mock data
Unit test: lead time calculation is accurate
Unit test: pagination works correctly
Unit test: returns meaningful error when repo does not exist or is inaccessible
Unit test: handles API timeout / connection failure gracefully

Constraints

Follow existing forgejo-mcp tool patterns and conventions (see src/forgejo_mcp/tools/workflows.py for examples)
Must work with Forgejo API, not GitHub-specific endpoints

Checklist

PR opened
Tests pass
No unrelated changes

Forgejo issue #25 — update_issue tool (most recent tool addition, pattern reference)
Forgejo issue #10 — set_label, comment_on_issue, create_repo tools (batch tool addition pattern)
pal-e-docs: dora-framework — DORA measurement automation roadmap
pal-e-docs: project-dora-metrics — parent project

### Type Feature ### Lineage New issue — created as part of DORA measurement expansion (2026-06-13). Agent DORA expansion line in the DORA framework measurement automation roadmap. ### Repo `ldraney/forgejo-mcp` ### User Story As an AI agent I want to query PR velocity, lead time, and rework rate from Forgejo So that I can reason about DORA metrics and make data-driven recommendations ### Context This is the "Agent DORA expansion" line in the DORA framework measurement automation roadmap. PR merge frequency and lead time are derivable from Forgejo's existing PR data. Rework rate can be approximated from review cycle count. Agents currently have no way to reason about DORA data. Adding query tools lets agents correlate Forgejo activity with DORA metrics, enabling data-driven decisions about code quality, deployment cadence, and process improvements. ### File Targets - `src/forgejo_mcp/tools/dora.py` — new tool module for DORA query tools - `src/forgejo_mcp/tools/__init__.py` — register new module via `register_all_tools()` (add `from . import dora` import) - `tests/test_dora_tools.py` — tests for new tools ### Feature Flag None required — new MCP tools are additive. ### Acceptance Criteria - [ ] At minimum one new MCP tool that queries PR merge frequency and lead time for a given repo over a time range - [ ] Returns structured data agents can reason about - [ ] Tool handles pagination for repos with many PRs - [ ] Time range parameter with sensible defaults (e.g., last 30 days) ### Test Expectations - [ ] Unit test: tool returns correct PR velocity for mock data - [ ] Unit test: lead time calculation is accurate - [ ] Unit test: pagination works correctly - [ ] Unit test: returns meaningful error when repo does not exist or is inaccessible - [ ] Unit test: handles API timeout / connection failure gracefully ### Constraints - Follow existing forgejo-mcp tool patterns and conventions (see `src/forgejo_mcp/tools/workflows.py` for examples) - Must work with Forgejo API, not GitHub-specific endpoints ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - Forgejo issue #25 — `update_issue` tool (most recent tool addition, pattern reference) - Forgejo issue #10 — `set_label`, `comment_on_issue`, `create_repo` tools (batch tool addition pattern) - pal-e-docs: `dora-framework` — DORA measurement automation roadmap - pal-e-docs: `project-dora-metrics` — parent project

ldraney added the

type:feature

label

2026-06-13 18:36:01 +00:00

ldraney commented

2026-06-13 19:16:31 +00:00

Author

Owner

Issue #28 Template Review

TEMPLATE CONFORMANCE

### Type present and valid (Feature)
### Lineage present and non-empty
### Repo present (ldraney/forgejo-mcp)
### User Story present with proper As a / I want / So that format
### Context present and non-empty
### File Targets present with specific paths
### Feature Flag present ("None required" -- reasonable for additive MCP tools)
### Acceptance Criteria present with - [ ] checkboxes
### Test Expectations present with - [ ] checkboxes
### Constraints present and non-empty
### Checklist present with standard items
### Related present

All required sections from template-issue-feature are present and non-empty.

CONTENT QUALITY

User Story: Clear and well-formed. The persona ("AI agent") and value prop ("reason about DORA metrics") are concrete.

Acceptance Criteria: Four checkboxes, all testable. "At minimum one new MCP tool" is pragmatic scoping -- leaves room for the implementer to add rework-rate tooling without requiring it.

Test Expectations: Three unit tests covering velocity, lead time, and pagination. Missing: error handling tests (e.g., invalid repo, API failure, empty time range). This is a nit, not a blocker -- the implementer can add those.

Extra sections: The issue includes ### What and ### Why sections that are not in the template. These are not blockers -- they provide useful context -- but they duplicate information already in ### User Story and ### Context. Minor redundancy.

FILE TARGETS REVIEW

Target	Exists?	Verdict
`src/forgejo_mcp/tools/dora.py`	No (new file)	Correct -- new module
`src/forgejo_mcp/server.py`	Yes	Misleading -- see below
`tests/test_dora_tools.py`	No (new file)	Correct -- new test file

Issue with server.py target: The issue lists server.py as needing modification to "register new tools." However, inspecting the actual codebase, tool registration happens in src/forgejo_mcp/tools/__init__.py via the register_all_tools() function (line 8: from . import workflows). A new dora module would need an additional import there, not a change to server.py. The file target is inaccurate and will misdirect the implementing agent.

Missing file target: src/forgejo_mcp/tools/__init__.py must be modified to add from . import dora in register_all_tools(). This file is not listed.

BLOCKERS

Inaccurate file target: server.py -- The issue states server.py needs modification to register new tools. In reality, registration happens in tools/__init__.py. This will misdirect the implementing agent. Fix: replace server.py with src/forgejo_mcp/tools/__init__.py in File Targets, or add __init__.py and clarify that server.py needs no changes.

NITS

Extra ### What and ### Why sections -- Not in the template. The information is useful but redundant with ### User Story and ### Context. Consider folding the content into those canonical sections for template consistency.
Test Expectations could be stronger -- No error-handling test cases listed (API failures, invalid repos, empty results). Not a blocker since the AC says "at minimum," but worth adding for implementer guidance.
### Related is vague -- References dora-metrics project and "DORA framework measurement automation roadmap" but does not link to specific issue numbers or pal-e-docs slugs. An agent cannot trace these references.

SCOPE CHECK

Single deployable unit (one new tool module + registration + tests)
No upstream dependencies that need to land first
Scope is appropriate for one PR

VERDICT: NEEDS_REWORK

Reason: The server.py file target is inaccurate. The implementing agent will modify the wrong file for tool registration. Add src/forgejo_mcp/tools/__init__.py to File Targets and either remove or correct the server.py entry. Once fixed, this issue is ready for next_up.

## Issue #28 Template Review ### TEMPLATE CONFORMANCE - [x] `### Type` present and valid (Feature) - [x] `### Lineage` present and non-empty - [x] `### Repo` present (`ldraney/forgejo-mcp`) - [x] `### User Story` present with proper As a / I want / So that format - [x] `### Context` present and non-empty - [x] `### File Targets` present with specific paths - [x] `### Feature Flag` present ("None required" -- reasonable for additive MCP tools) - [x] `### Acceptance Criteria` present with `- [ ]` checkboxes - [x] `### Test Expectations` present with `- [ ]` checkboxes - [x] `### Constraints` present and non-empty - [x] `### Checklist` present with standard items - [x] `### Related` present All required sections from `template-issue-feature` are present and non-empty. ### CONTENT QUALITY **User Story:** Clear and well-formed. The persona ("AI agent") and value prop ("reason about DORA metrics") are concrete. **Acceptance Criteria:** Four checkboxes, all testable. "At minimum one new MCP tool" is pragmatic scoping -- leaves room for the implementer to add rework-rate tooling without requiring it. **Test Expectations:** Three unit tests covering velocity, lead time, and pagination. Missing: error handling tests (e.g., invalid repo, API failure, empty time range). This is a nit, not a blocker -- the implementer can add those. **Extra sections:** The issue includes `### What` and `### Why` sections that are not in the template. These are not blockers -- they provide useful context -- but they duplicate information already in `### User Story` and `### Context`. Minor redundancy. ### FILE TARGETS REVIEW | Target | Exists? | Verdict | |--------|---------|---------| | `src/forgejo_mcp/tools/dora.py` | No (new file) | Correct -- new module | | `src/forgejo_mcp/server.py` | Yes | **Misleading** -- see below | | `tests/test_dora_tools.py` | No (new file) | Correct -- new test file | **Issue with `server.py` target:** The issue lists `server.py` as needing modification to "register new tools." However, inspecting the actual codebase, tool registration happens in `src/forgejo_mcp/tools/__init__.py` via the `register_all_tools()` function (line 8: `from . import workflows`). A new `dora` module would need an additional import there, not a change to `server.py`. The file target is inaccurate and will misdirect the implementing agent. **Missing file target:** `src/forgejo_mcp/tools/__init__.py` must be modified to add `from . import dora` in `register_all_tools()`. This file is not listed. ### BLOCKERS 1. **Inaccurate file target: `server.py`** -- The issue states `server.py` needs modification to register new tools. In reality, registration happens in `tools/__init__.py`. This will misdirect the implementing agent. Fix: replace `server.py` with `src/forgejo_mcp/tools/__init__.py` in File Targets, or add `__init__.py` and clarify that `server.py` needs no changes. ### NITS 1. **Extra `### What` and `### Why` sections** -- Not in the template. The information is useful but redundant with `### User Story` and `### Context`. Consider folding the content into those canonical sections for template consistency. 2. **Test Expectations could be stronger** -- No error-handling test cases listed (API failures, invalid repos, empty results). Not a blocker since the AC says "at minimum," but worth adding for implementer guidance. 3. **`### Related` is vague** -- References `dora-metrics` project and "DORA framework measurement automation roadmap" but does not link to specific issue numbers or pal-e-docs slugs. An agent cannot trace these references. ### SCOPE CHECK - [x] Single deployable unit (one new tool module + registration + tests) - [x] No upstream dependencies that need to land first - [x] Scope is appropriate for one PR ### VERDICT: NEEDS_REWORK **Reason:** The `server.py` file target is inaccurate. The implementing agent will modify the wrong file for tool registration. Add `src/forgejo_mcp/tools/__init__.py` to File Targets and either remove or correct the `server.py` entry. Once fixed, this issue is ready for `next_up`.

ldraney commented

2026-06-13 19:21:17 +00:00

Author

Owner

Updated per QA review: fixed file targets (tools/__init__.py for registration via register_all_tools(), workflows.py pattern for implementation reference), removed duplicate ### What and ### Why sections (User Story and Context already cover this), added error-handling test expectations (invalid repo, API timeout), fixed Related references with explicit issue numbers and pal-e-docs slugs.

Updated per QA review: fixed file targets (`tools/__init__.py` for registration via `register_all_tools()`, `workflows.py` pattern for implementation reference), removed duplicate `### What` and `### Why` sections (User Story and Context already cover this), added error-handling test expectations (invalid repo, API timeout), fixed Related references with explicit issue numbers and pal-e-docs slugs.

ldraney commented

2026-06-13 19:23:52 +00:00

Author

Owner

Issue #28 Template Review (Re-review)

TEMPLATE CONFORMANCE

### Type header present and valid (Feature)
All 12 required sections present: Type, Lineage, Repo, User Story, Context, File Targets, Feature Flag, Acceptance Criteria, Test Expectations, Constraints, Checklist, Related
All sections non-empty with substantive content
Checkboxes use - [ ] format in Acceptance Criteria, Test Expectations, and Checklist

PREVIOUS BLOCKER RESOLUTION

All five blockers from the prior review are resolved:

server.py removed from file targets -- RESOLVED. File Targets now correctly lists only tools/dora.py, tools/__init__.py, and tests/test_dora_tools.py. No mention of server.py.
tools/init.py listed for registration -- RESOLVED. Explicitly states: "register new module via register_all_tools() (add from . import dora import)". This matches the actual pattern in the codebase where __init__.py imports tool modules.
Duplicate ### What and ### Why sections removed -- RESOLVED. Issue now uses the correct template sections (### User Story, ### Context) with no duplicates.
Error-handling test expectations added -- RESOLVED. Two error-case tests added: "returns meaningful error when repo does not exist or is inaccessible" and "handles API timeout / connection failure gracefully".
Related references traceable -- RESOLVED. All four references verified:
- Forgejo #25 -- exists (closed PR: "feat: add update_issue MCP tool")
- Forgejo #10 -- exists (closed PR: "feat: add set_label, comment_on_issue, and create_repo MCP tools")
- dora-framework -- resolves in pal-e-docs (DORA Framework: Platform Axiom)
- project-dora-metrics -- resolves in pal-e-docs (Project: DORA Metrics)

CONTENT QUALITY

User Story: Well-formed As/I want/So that. Agent persona is appropriate for MCP tooling.
Context: Clear motivation linking to DORA measurement automation roadmap. Explains the gap (agents have no DORA query capability) and the value (data-driven reasoning).
File Targets: Specific paths matching the actual repo structure. The __init__.py registration instruction includes the exact import statement needed. The pattern reference to workflows.py is accurate -- that is the only existing tool module.
Feature Flag: "None required" is correct -- additive MCP tools do not need feature flags.
Acceptance Criteria: Four testable criteria with checkboxes. Covers structured output, pagination, and time-range defaults.
Test Expectations: Five test cases covering happy path (velocity, lead time), pagination, and two error scenarios. Run command not specified, but the test file path (tests/test_dora_tools.py) is clear enough for pytest tests/test_dora_tools.py.
Constraints: References existing tool patterns and Forgejo API compatibility.

BLOCKERS

None.

NITS

Test Expectations: Missing an explicit run command (e.g., pytest tests/test_dora_tools.py). Template guidance says "Run command: pytest tests/ -k test_name or equivalent." Low impact since the test file path is self-evident.
Acceptance Criteria: "At minimum one new MCP tool" is slightly vague -- the Context section implies at least PR merge frequency, lead time, and rework rate tools, but the criteria only commits to one. Consider specifying which tools are in-scope vs. stretch.

VERDICT: APPROVED

## Issue #28 Template Review (Re-review) ### TEMPLATE CONFORMANCE - [x] `### Type` header present and valid (Feature) - [x] All 12 required sections present: Type, Lineage, Repo, User Story, Context, File Targets, Feature Flag, Acceptance Criteria, Test Expectations, Constraints, Checklist, Related - [x] All sections non-empty with substantive content - [x] Checkboxes use `- [ ]` format in Acceptance Criteria, Test Expectations, and Checklist ### PREVIOUS BLOCKER RESOLUTION All five blockers from the prior review are resolved: 1. **server.py removed from file targets** -- RESOLVED. File Targets now correctly lists only `tools/dora.py`, `tools/__init__.py`, and `tests/test_dora_tools.py`. No mention of `server.py`. 2. **tools/__init__.py listed for registration** -- RESOLVED. Explicitly states: "register new module via `register_all_tools()` (add `from . import dora` import)". This matches the actual pattern in the codebase where `__init__.py` imports tool modules. 3. **Duplicate ### What and ### Why sections removed** -- RESOLVED. Issue now uses the correct template sections (`### User Story`, `### Context`) with no duplicates. 4. **Error-handling test expectations added** -- RESOLVED. Two error-case tests added: "returns meaningful error when repo does not exist or is inaccessible" and "handles API timeout / connection failure gracefully". 5. **Related references traceable** -- RESOLVED. All four references verified: - Forgejo #25 -- exists (closed PR: "feat: add update_issue MCP tool") - Forgejo #10 -- exists (closed PR: "feat: add set_label, comment_on_issue, and create_repo MCP tools") - `dora-framework` -- resolves in pal-e-docs (DORA Framework: Platform Axiom) - `project-dora-metrics` -- resolves in pal-e-docs (Project: DORA Metrics) ### CONTENT QUALITY - **User Story**: Well-formed As/I want/So that. Agent persona is appropriate for MCP tooling. - **Context**: Clear motivation linking to DORA measurement automation roadmap. Explains the gap (agents have no DORA query capability) and the value (data-driven reasoning). - **File Targets**: Specific paths matching the actual repo structure. The `__init__.py` registration instruction includes the exact import statement needed. The pattern reference to `workflows.py` is accurate -- that is the only existing tool module. - **Feature Flag**: "None required" is correct -- additive MCP tools do not need feature flags. - **Acceptance Criteria**: Four testable criteria with checkboxes. Covers structured output, pagination, and time-range defaults. - **Test Expectations**: Five test cases covering happy path (velocity, lead time), pagination, and two error scenarios. Run command not specified, but the test file path (`tests/test_dora_tools.py`) is clear enough for `pytest tests/test_dora_tools.py`. - **Constraints**: References existing tool patterns and Forgejo API compatibility. ### BLOCKERS None. ### NITS 1. **Test Expectations**: Missing an explicit run command (e.g., `pytest tests/test_dora_tools.py`). Template guidance says "Run command: `pytest tests/ -k test_name` or equivalent." Low impact since the test file path is self-evident. 2. **Acceptance Criteria**: "At minimum one new MCP tool" is slightly vague -- the Context section implies at least PR merge frequency, lead time, and rework rate tools, but the criteria only commits to one. Consider specifying which tools are in-scope vs. stretch. ### VERDICT: APPROVED

ldraney referenced this issue from a commit

2026-06-13 19:52:52 +00:00

feat: add DORA query tools for agent reasoning

ldraney referenced this issue from a pull request that will close it,

2026-06-13 19:53:16 +00:00

feat: add DORA query tools for agent reasoning #31

ldraney

2026-06-13 19:55:10 +00:00