deepak-menan-r/jiraresolver

Purpose and Runtime Entry Points

This is a Python 3.10+ agentic Jira resolver: given a Jira ticket ID, it discovers the relevant GitHub repository, proposes a fix, obtains human approval, then creates a PR and updates Jira. It runs as two local processes:

• Agent CLI: src/jira_resolver_mcp/__main__.py, src/jira_resolver_mcp/main.py

• MCP HTTP server: mcp_server/__main__.py, mcp_server/run.py

Agent Orchestration

LangGraph is the control-plane runtime. build_workflow() wires a stateful graph beginning with ticket intake and ending in either rejection, clarification, retry exhaustion, or GitHub operations.

• Graph and conditional routing: src/jira_resolver_mcp/workflow.py

• Per-stage logic: src/jira_resolver_mcp/nodes.py

• Cross-node state/checkpoint payload: src/jira_resolver_mcp/state.py

The graph pauses through a human-approval interrupt before any write to GitHub.

Ticket Intake and Repository Navigation

The ticket stage fetches Jira data, validates required details, extracts repository/file hints, marks the ticket Working, and terminates early for missing information. Navigation resolves a repo without a supplied URL: it lists accessible repositories, searches code across them, identifies the likely match, reads architecture files, searches within the target repository, ranks candidates, and loads source content.

• Agent stages: src/jira_resolver_mcp/nodes.py

• LLM-assisted extraction/selection: src/jira_resolver_mcp/llm_router.py

• Jira/repository server tools: mcp_server/tools_jira.py, mcp_server/tools_repo.py

Ambiguous repository selection is a boundary: the system posts a Jira clarification and waits rather than modifying code.

Planning, Implementation, and Review Loop

Once candidate file contents are in graph state, the planner produces an implementation plan. The implementer generates complete updated file contents, while the reviewer independently assesses the proposal. Rejected reviews increment retries and route back to implementation; acceptance requires reviewer confidence of at least 0.75 and transitions Jira to In Review.

• LLM interface and placeholder provider bodies: src/jira_resolver_mcp/llm_router.py

• Workflow stages/retry behavior: src/jira_resolver_mcp/nodes.py, src/jira_resolver_mcp/workflow.py

LLM integration is intentionally incomplete; configured OpenRouter and Google API credentials are expected future provider options.

Approval and GitHub Write Boundary

Human approval separates read/analysis operations from repository mutation. On approval, GitHub operations create a timestamped jira/<ticket>-... branch, apply generated file changes or patch, create a PR, checkpoint state for resume paths, post the PR URL to Jira, and mark the ticket PR Created.

• Approval and finalization stages: src/jira_resolver_mcp/nodes.py

• GitHub mutation handlers: mcp_server/tools_github.py

• Resume-oriented CLI flow: src/jira_resolver_mcp/main.py

MCP Service Boundary

The agent never calls Jira or GitHub directly. Its typed client wraps the MCP server’s single tool-dispatch API (POST /tools/call), while FastAPI registers and dispatches Jira, repository-discovery, and GitHub tools. Health and tool-list endpoints support local operation.

• Agent-side HTTP abstraction: src/jira_resolver_mcp/mcp_client.py

• FastAPI app/tool registry: mcp_server/app.py

• MCP server configuration: mcp_server/config.py

Infrastructure and External Services

The MCP server runs under Uvicorn/FastAPI, normally at http://localhost:8080. It requires Jira Cloud REST credentials and a GitHub PAT with repository access; repository discovery can be scoped to a GitHub organization or user. Environment-driven configuration covers service URLs, credentials, default branch, host/port, and optional LLM provider keys.

• Server process: mcp_server/run.py

• Agent configuration: src/jira_resolver_mcp/config.py

• Environment contract: .env.example