mergescope 0.1.0__tar.gz

mergescope-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --dev
+      - run: uv run pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mergescope-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+*.log
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+BUILD.md

mergescope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Caminoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mergescope-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: mergescope
+Version: 0.1.0
+Summary: Audit merged PRs against Jira tickets using a LangGraph agent and MCP tools
+Project-URL: Homepage, https://github.com/martin5211/MergeScope
+Project-URL: Repository, https://github.com/martin5211/MergeScope
+Project-URL: Issues, https://github.com/martin5211/MergeScope/issues
+Author: Martin Caminoa
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: langchain-anthropic<2.0,>=0.3
+Requires-Dist: langchain-aws<2.0,>=0.2
+Requires-Dist: langchain-mcp-adapters<2.0,>=0.1
+Requires-Dist: langchain-openai<2.0,>=0.3
+Requires-Dist: langgraph<2.0,>=0.4
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<15.0,>=13.0
+Description-Content-Type: text/markdown
+
+# MergeScope
+
+Audits merged PRs against Jira tickets. Extracts Jira IDs from PR titles, descriptions, branch names, and commit messages, then validates each ticket's fixVersion against your expected release.
+
+Powered by a LangGraph agent that talks to GitHub and Jira through MCP servers. Works standalone or with Amazon Q.
+
+## Install
+
+```bash
+uvx mergescope --help
+```
+
+Or permanently:
+
+```bash
+uv tool install mergescope
+```
+
+## Usage
+
+```bash
+mergescope \
+  -f 2026-03-01 \
+  -t 2026-03-31 \
+  -v "1.2.0" \
+  -r company/backend
+```
+
+| Flag | Description |
+|---|---|
+| `-f`, `--from-date` | Start date (YYYY-MM-DD) |
+| `-t`, `--to-date` | End date (YYYY-MM-DD) |
+| `-v`, `--fix-version` | Expected Jira fixVersion |
+| `-r`, `--repo` | GitHub repo (owner/repo) |
+| `-c`, `--config` | Config file (default: `mergescope.yaml`) |
+| `--mcp-config` | Amazon Q MCP config path |
+| `--llm-provider` | `anthropic`, `bedrock`, `copilot`, or `local` |
+| `--llm-model` | Model ID |
+| `--llm-base-url` | API base URL (copilot/local) |
+| `--language` | Response language (e.g. Spanish) |
+| `--verbose` | Debug logging |
+
+### Multilingual prompts
+
+Set a custom prompt in any language via `mergescope.yaml`:
+
+```yaml
+language: "es"
+response_language: "Spanish"
+prompt_template: |
+  Necesito auditar tickets mergeados entre {from_date} y {to_date}.
+  La fixVersion esperada es {fix_version}.
+  Extrae los IDs de JIRA desde los merge commits del repositorio {repo}
+  y valida su fixVersion.
+```
+
+## Configuration
+
+Add a `mergescope.yaml` in your project root:
+
+```yaml
+repo: "nice/java-project"
+jira_project_prefix: "PROJ"
+jira_base_url: "https://company.jira.com"
+
+llm:
+  provider: "anthropic"       # anthropic, bedrock, copilot, local
+  model: "claude-sonnet-4-6-20250620"
+
+mcp:
+  servers:
+    github:
+      name: "github-mcp-server"
+    jira:
+      name: "atlassian-mcp-server"
+```
+
+### LLM providers
+
+| Provider | Model example | Notes |
+|---|---|---|
+| `anthropic` | `claude-sonnet-4-6-20250620` | Uses `ANTHROPIC_API_KEY` |
+| `bedrock` | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Uses AWS credentials |
+| `copilot` | `claude-sonnet-4` | Set `base_url` to Copilot endpoint |
+| `local` | `qwen3-8b` | LM Studio, Ollama, or any OpenAI-compatible server |
+
+### MCP servers
+
+Two modes — pick what fits your setup:
+
+**With Amazon Q** (default): just set server names. MergeScope finds them in `~/.aws/amazonq/mcp.json` or `.amazonq/mcp.json`.
+
+**Standalone** (no Amazon Q): define `command`, `args`, and `env` directly:
+
+```yaml
+mcp:
+  servers:
+    github:
+      name: "github-mcp-server"
+      command: "npx"
+      args: ["-y", "@anthropic/github-mcp-server"]
+      env:
+        GITHUB_TOKEN: "ghp_..."
+    jira:
+      name: "atlassian-mcp-server"
+      command: "npx"
+      args: ["-y", "@anthropic/atlassian-mcp-server"]
+      env:
+        JIRA_API_TOKEN: "..."
+        JIRA_URL: "https://company.jira.com"
+```
+
+You can mix both — some servers inline, others from Amazon Q.
+
+### Environment variables
+
+`MERGESCOPE_REPO`, `MERGESCOPE_LLM_PROVIDER`, `MERGESCOPE_LLM_MODEL`, `MERGESCOPE_LLM_BASE_URL`, `MERGESCOPE_LLM_API_KEY`, `MERGESCOPE_JIRA_BASE_URL`, `MERGESCOPE_LANGUAGE`
+
+## Requirements
+
+- Python 3.11+
+- GitHub and Jira MCP servers (standalone or via Amazon Q)
+- An LLM: Anthropic API key, AWS credentials, GitHub Copilot, or a local server
+
+## Development
+
+```bash
+git clone https://github.com/martin5211/MergeScope.git
+cd MergeScope
+uv venv && uv pip install -e .
+pytest
+```

mergescope-0.1.0/README.md

@@ -0,0 +1,132 @@
+# MergeScope
+
+Audits merged PRs against Jira tickets. Extracts Jira IDs from PR titles, descriptions, branch names, and commit messages, then validates each ticket's fixVersion against your expected release.
+
+Powered by a LangGraph agent that talks to GitHub and Jira through MCP servers. Works standalone or with Amazon Q.
+
+## Install
+
+```bash
+uvx mergescope --help
+```
+
+Or permanently:
+
+```bash
+uv tool install mergescope
+```
+
+## Usage
+
+```bash
+mergescope \
+  -f 2026-03-01 \
+  -t 2026-03-31 \
+  -v "1.2.0" \
+  -r company/backend
+```
+
+| Flag | Description |
+|---|---|
+| `-f`, `--from-date` | Start date (YYYY-MM-DD) |
+| `-t`, `--to-date` | End date (YYYY-MM-DD) |
+| `-v`, `--fix-version` | Expected Jira fixVersion |
+| `-r`, `--repo` | GitHub repo (owner/repo) |
+| `-c`, `--config` | Config file (default: `mergescope.yaml`) |
+| `--mcp-config` | Amazon Q MCP config path |
+| `--llm-provider` | `anthropic`, `bedrock`, `copilot`, or `local` |
+| `--llm-model` | Model ID |
+| `--llm-base-url` | API base URL (copilot/local) |
+| `--language` | Response language (e.g. Spanish) |
+| `--verbose` | Debug logging |
+
+### Multilingual prompts
+
+Set a custom prompt in any language via `mergescope.yaml`:
+
+```yaml
+language: "es"
+response_language: "Spanish"
+prompt_template: |
+  Necesito auditar tickets mergeados entre {from_date} y {to_date}.
+  La fixVersion esperada es {fix_version}.
+  Extrae los IDs de JIRA desde los merge commits del repositorio {repo}
+  y valida su fixVersion.
+```
+
+## Configuration
+
+Add a `mergescope.yaml` in your project root:
+
+```yaml
+repo: "nice/java-project"
+jira_project_prefix: "PROJ"
+jira_base_url: "https://company.jira.com"
+
+llm:
+  provider: "anthropic"       # anthropic, bedrock, copilot, local
+  model: "claude-sonnet-4-6-20250620"
+
+mcp:
+  servers:
+    github:
+      name: "github-mcp-server"
+    jira:
+      name: "atlassian-mcp-server"
+```
+
+### LLM providers
+
+| Provider | Model example | Notes |
+|---|---|---|
+| `anthropic` | `claude-sonnet-4-6-20250620` | Uses `ANTHROPIC_API_KEY` |
+| `bedrock` | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Uses AWS credentials |
+| `copilot` | `claude-sonnet-4` | Set `base_url` to Copilot endpoint |
+| `local` | `qwen3-8b` | LM Studio, Ollama, or any OpenAI-compatible server |
+
+### MCP servers
+
+Two modes — pick what fits your setup:
+
+**With Amazon Q** (default): just set server names. MergeScope finds them in `~/.aws/amazonq/mcp.json` or `.amazonq/mcp.json`.
+
+**Standalone** (no Amazon Q): define `command`, `args`, and `env` directly:
+
+```yaml
+mcp:
+  servers:
+    github:
+      name: "github-mcp-server"
+      command: "npx"
+      args: ["-y", "@anthropic/github-mcp-server"]
+      env:
+        GITHUB_TOKEN: "ghp_..."
+    jira:
+      name: "atlassian-mcp-server"
+      command: "npx"
+      args: ["-y", "@anthropic/atlassian-mcp-server"]
+      env:
+        JIRA_API_TOKEN: "..."
+        JIRA_URL: "https://company.jira.com"
+```
+
+You can mix both — some servers inline, others from Amazon Q.
+
+### Environment variables
+
+`MERGESCOPE_REPO`, `MERGESCOPE_LLM_PROVIDER`, `MERGESCOPE_LLM_MODEL`, `MERGESCOPE_LLM_BASE_URL`, `MERGESCOPE_LLM_API_KEY`, `MERGESCOPE_JIRA_BASE_URL`, `MERGESCOPE_LANGUAGE`
+
+## Requirements
+
+- Python 3.11+
+- GitHub and Jira MCP servers (standalone or via Amazon Q)
+- An LLM: Anthropic API key, AWS credentials, GitHub Copilot, or a local server
+
+## Development
+
+```bash
+git clone https://github.com/martin5211/MergeScope.git
+cd MergeScope
+uv venv && uv pip install -e .
+pytest
+```

mergescope-0.1.0/mergescope.yaml

@@ -0,0 +1,81 @@
+# MergeScope configuration
+# Copy this file to your project root and adjust values.
+
+# GitHub repository (owner/repo)
+repo: ""
+
+# Jira settings
+jira_project_prefix: ""          # e.g. "PROJ" — leave empty to match all projects
+jira_base_url: ""                # e.g. "https://company.jira.com"
+
+# Language for the audit prompt and report
+language: "en"
+response_language: "English"
+
+# Custom prompt template (supports {repo}, {from_date}, {to_date}, {fix_version})
+# prompt_template: |
+#   Necesito auditar tickets mergeados entre {from_date} y {to_date}.
+#   La fixVersion esperada es {fix_version}.
+#   Extrae los IDs de JIRA desde los merge commits del repositorio {repo}
+#   y valida su fixVersion.
+
+# LLM provider and model
+# Supported providers: anthropic, bedrock, copilot, local
+llm:
+  provider: "anthropic"
+  model: "claude-sonnet-4-6-20250620"
+  # base_url: ""                 # override API endpoint (required for copilot/local)
+  # api_key: ""                  # override API key (or use env vars below)
+
+# Provider examples:
+#
+# Anthropic (default):
+#   provider: "anthropic"
+#   model: "claude-sonnet-4-6-20250620"
+#   # uses ANTHROPIC_API_KEY env var
+#
+# AWS Bedrock:
+#   provider: "bedrock"
+#   model: "us.anthropic.claude-sonnet-4-20250514-v1:0"
+#   # uses AWS credentials
+#
+# GitHub Copilot:
+#   provider: "copilot"
+#   model: "claude-sonnet-4"
+#   base_url: "https://api.githubcopilot.com"
+#   # uses GITHUB_TOKEN or MERGESCOPE_LLM_API_KEY env var
+#
+# Local LLM (LM Studio, Ollama, etc.):
+#   provider: "local"
+#   model: "qwen3-9b"
+#   base_url: "http://localhost:1234/v1"
+
+# MCP server configuration
+# Two modes: inline (standalone) or Amazon Q lookup (name-only).
+# When "command" is set, the server runs directly — no Amazon Q needed.
+# When only "name" is set, it looks up that server in Amazon Q config.
+mcp:
+  config_path: ""                # auto-discovers Amazon Q config if empty
+  servers:
+    github:
+      name: "github-mcp-server"
+    jira:
+      name: "atlassian-mcp-server"
+
+# Standalone example (no Amazon Q required):
+#
+# mcp:
+#   servers:
+#     github:
+#       name: "github-mcp-server"
+#       command: "npx"
+#       args: ["-y", "@anthropic/github-mcp-server"]
+#       env:
+#         GITHUB_TOKEN: "ghp_..."
+#     jira:
+#       name: "atlassian-mcp-server"
+#       command: "npx"
+#       args: ["-y", "@anthropic/atlassian-mcp-server"]
+#       env:
+#         JIRA_API_TOKEN: "..."
+#         JIRA_URL: "https://company.atlassian.net"

mergescope-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mergescope"
+version = "0.1.0"
+description = "Audit merged PRs against Jira tickets using a LangGraph agent and MCP tools"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Martin Caminoa" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "langgraph>=0.4,<2.0",
+    "langchain-mcp-adapters>=0.1,<2.0",
+    "langchain-anthropic>=0.3,<2.0",
+    "langchain-aws>=0.2,<2.0",
+    "langchain-openai>=0.3,<2.0",
+    "pyyaml>=6.0,<7.0",
+    "rich>=13.0,<15.0",
+]
+
+[project.scripts]
+mergescope = "mergescope.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/martin5211/MergeScope"
+Repository = "https://github.com/martin5211/MergeScope"
+Issues = "https://github.com/martin5211/MergeScope/issues"
+
+[dependency-groups]
+dev = ["pytest>=9.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mergescope"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mergescope-0.1.0/src/mergescope/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mergescope-0.1.0/src/mergescope/__main__.py

@@ -0,0 +1,3 @@
+from mergescope.cli import main
+
+main()

mergescope-0.1.0/src/mergescope/agent.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from langgraph.graph import MessagesState, StateGraph, START
+from langgraph.prebuilt import ToolNode, tools_condition
+
+from mergescope.config import MergeScopeConfig
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT = """\
+You are MergeScope, an audit agent that cross-references GitHub merge activity with Jira tickets.
+
+You have access to GitHub and Jira tools via MCP servers. Use the available tools to complete the audit.
+
+## Instructions
+
+1. **Fetch merge activity**: Use the GitHub tools to list merged pull requests (or merge commits) in the given repository and date range. Get enough detail: PR title, body/description, branch name, commit messages, and commit SHAs.
+
+2. **Extract Jira IDs**: From EACH pull request, look for Jira ticket IDs in ALL of these places:
+   - PR title
+   - PR body / description (both short and long)
+   - Branch name (e.g. `feat/PROJ-123-something`, `PROJ-456`, `bugfix/proj-789`)
+   - Individual commit messages
+   Jira IDs follow the pattern: 2+ letters, a hyphen, then digits (e.g. PROJ-123, AB-1). They may appear in brackets [PROJ-123], lowercase, or mixed case. Normalize all to UPPERCASE and deduplicate.
+
+3. **Validate in Jira**: For each unique Jira ID found, use the Jira/Atlassian tools to fetch:
+   - The ticket summary (title)
+   - The fixVersion field
+   Compare fixVersion against the expected version provided.
+
+4. **Return structured JSON** with this exact schema:
+```json
+{{
+  "tickets": [
+    {{
+      "jira_id": "PROJ-123",
+      "title": "Ticket summary from Jira",
+      "fix_version": "actual fixVersion or null",
+      "expected_version": "the expected version",
+      "status": "MATCH | MISMATCH | NOT_FOUND | NO_FIX_VERSION"
+    }}
+  ],
+  "unlinked_commits": [
+    {{
+      "sha": "full commit SHA",
+      "message": "first line of commit message",
+      "url": "https://github.com/owner/repo/commit/SHA"
+    }}
+  ]
+}}
+```
+
+Status rules:
+- `MATCH`: fixVersion equals expected version
+- `MISMATCH`: fixVersion exists but differs from expected
+- `NOT_FOUND`: Jira ticket does not exist or lookup failed
+- `NO_FIX_VERSION`: ticket exists but has no fixVersion set
+
+Include in `unlinked_commits` every merge commit or squash commit that has NO Jira ID anywhere (title, body, branch, message).
+
+{language_instruction}
+
+Respond ONLY with the JSON object. No markdown fences, no explanation.\
+"""
+
+
+def _build_system_prompt(config: MergeScopeConfig) -> str:
+    lang = config.response_language
+    if lang and lang.lower() != "english":
+        instruction = f"Write all ticket titles and the JSON string values in {lang} if the source is in that language, otherwise keep the original language."
+    else:
+        instruction = ""
+    return SYSTEM_PROMPT.format(language_instruction=instruction)
+
+
+_PROVIDERS = ("anthropic", "bedrock", "copilot", "local")
+
+
+def _create_llm(config: MergeScopeConfig):
+    provider = config.llm.provider.lower()
+    model_id = config.llm.model
+    base_url = config.llm.base_url or None
+    api_key = config.llm.api_key or None
+
+    if provider == "anthropic":
+        from langchain_anthropic import ChatAnthropic
+        return ChatAnthropic(model=model_id)
+
+    if provider == "bedrock":
+        from langchain_aws import ChatBedrock
+        return ChatBedrock(model_id=model_id)
+
+    if provider == "copilot":
+        from langchain_openai import ChatOpenAI
+        return ChatOpenAI(
+            model=model_id,
+            base_url=base_url or "https://api.githubcopilot.com",
+            api_key=api_key or None,
+        )
+
+    if provider == "local":
+        from langchain_openai import ChatOpenAI
+        return ChatOpenAI(
+            model=model_id,
+            base_url=base_url or "http://localhost:1234/v1",
+            api_key=api_key or "lm-studio",
+        )
+
+    raise ValueError(
+        f"Unsupported LLM provider: '{provider}'. "
+        f"Choose from: {', '.join(_PROVIDERS)}"
+    )
+
+
+def build_agent(tools: list, config: MergeScopeConfig):
+    model = _create_llm(config)
+    model_with_tools = model.bind_tools(tools)
+
+    async def call_model(state: MessagesState) -> dict:
+        response = await model_with_tools.ainvoke(state["messages"])
+        return {"messages": [response]}
+
+    graph = StateGraph(MessagesState)
+    graph.add_node("call_model", call_model)
+    graph.add_node("tools", ToolNode(tools))
+    graph.add_edge(START, "call_model")
+    graph.add_conditional_edges("call_model", tools_condition)
+    graph.add_edge("tools", "call_model")
+
+    return graph.compile()
+
+
+def build_prompt(config: MergeScopeConfig, repo: str, from_date: str, to_date: str, fix_version: str) -> list:
+    system = _build_system_prompt(config)
+    human = config.prompt_template.format(
+        repo=repo,
+        from_date=from_date,
+        to_date=to_date,
+        fix_version=fix_version,
+    )
+    return [
+        SystemMessage(content=system),
+        HumanMessage(content=human),
+    ]
+
+
+def parse_agent_output(content: str) -> dict[str, Any]:
+    text = content.strip()
+    fence_match = re.search(r"```(?:json)?\s*\n?(.*?)\n?\s*```", text, re.DOTALL)
+    if fence_match:
+        text = fence_match.group(1).strip()
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        logger.error("Failed to parse agent output as JSON: %s", exc)
+        logger.debug("Raw output:\n%s", content)
+        raise ValueError(
+            "Agent did not return valid JSON. Raw output logged at DEBUG level."
+        ) from exc