{
  "markdown": "# GitHub Issue MCP Assistant\n\n[![CI](https://github.com/sarim-aliii/github-issue-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sarim-aliii/github-issue-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/github-issue-mcp)](https://www.npmjs.com/package/github-issue-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-blue)](https://registry.modelcontextprotocol.io/)\n\nAn AI-powered GitHub issue management system built with **Model Context Protocol (MCP)**, **Google Gemini**, **TypeScript**, and the **GitHub REST API**.\n\nGitHub Issue MCP turns a short natural-language bug report into a structured GitHub issue while intelligently checking for existing duplicates before anything is created.\n\nThe project demonstrates a controlled **agentic workflow** where Gemini can reason and use MCP tools, while persistent GitHub write operations remain explicitly controlled by the application and the user.\n\nThe MCP server is also packaged as a reusable npm package so it can be embedded into other Node.js applications or launched directly as an MCP stdio server.\n\n---\n\n## ✨ Features\n\n- 🤖 **AI-powered issue generation** using Google Gemini\n- 🔍 **Duplicate issue detection**\n- 🧠 **Semantic duplicate analysis** instead of relying only on keyword matching\n- 📝 Interactive collection of additional issue details\n- 🏷️ Repository label retrieval and validation\n- 👤 **Human approval before issue creation**\n- 🔐 Prevents the autonomous AI agent from directly creating GitHub issues\n- 🔄 Automatic retry handling for temporary Gemini API failures\n- 🚦 Daily Gemini quota detection without unnecessary retries\n- ⚙️ Configurable Gemini model and retry behavior\n- 🧪 Comprehensive unit, workflow, and integration tests\n- 📦 Reusable MCP server architecture\n- 🔌 Published npm package\n- 🚀 Executable `github-issue-mcp` MCP CLI\n- 🌐 Published to the official MCP Registry\n- 🛡️ Phase-restricted AI tool access\n- 🔗 Separation between AI reasoning and external GitHub operations\n\n---\n\n# 📦 Installation\n\n## Install from npm\n\n```bash\nnpm install github-issue-mcp\n\nThe package is available on npm as:\n\ngithub-issue-mcp\n\nCurrent release:\n\nv1.1.2\n🚀 Quick Start\nRun as an MCP server\n\nThe package exposes an executable MCP server CLI.\n\nnpx -y github-issue-mcp\n\nThe server communicates using MCP over stdio.\n\nThis is the recommended approach when configuring the server in an MCP-compatible client.\n\n🔌 MCP Client Configuration\n\nGitHub Issue MCP can be used with any MCP-compatible client that supports stdio servers.\n\nUsing npx\n\nThe simplest configuration uses the published npm package:\n\n{\n  \"mcpServers\": {\n    \"github-issue-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"github-issue-mcp\"\n      ],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"YOUR_GITHUB_TOKEN\",\n        \"GITHUB_OWNER\": \"YOUR_GITHUB_OWNER\",\n        \"GITHUB_REPO\": \"YOUR_GITHUB_REPO\",\n        \"GEMINI_API_KEY\": \"YOUR_GEMINI_API_KEY\"\n      }\n    }\n  }\n}\n\nThe MCP client starts:\n\nnpx -y github-issue-mcp\n\nand communicates with the server over stdio.\n\n⚙️ Configuration\n\nCreate a .env file when running the project locally.\n\nGITHUB_TOKEN=your_github_token\nGITHUB_OWNER=your_github_username\nGITHUB_REPO=your_repository\n\n\nGEMINI_API_KEY=your_gemini_api_key\n\n\nGEMINI_MODEL=gemini-3.6-flash\nGEMINI_MAX_RETRIES=3\nGEMINI_RETRY_BASE_DELAY=1000\n\n\nDEBUG=false\nEnvironment variables\nVariable\tRequired\tDescription\tDefault\nGITHUB_TOKEN\tYes\tGitHub API authentication token\tRequired\nGITHUB_OWNER\tYes\tGitHub repository owner or organization\tRequired\nGITHUB_REPO\tYes\tGitHub repository name\tRequired\nGEMINI_API_KEY\tYes\tGoogle Gemini API key\tRequired\nGEMINI_MODEL\tNo\tGemini model used by the AI client\tgemini-3.6-flash\nGEMINI_MAX_RETRIES\tNo\tMaximum number of Gemini retries\t3\nGEMINI_RETRY_BASE_DELAY\tNo\tBase retry delay in milliseconds\t1000\nDEBUG\tNo\tEnables debug behavior/logging\tfalse\n\nNever commit .env, GitHub tokens, or Gemini API keys to Git.\n\n🧩 MCP Tools\n\nThe MCP server exposes the following tools:\n\nTool\tPurpose\ngenerate_issue\tGenerate a structured GitHub issue\ncreate_github_issue\tCreate an issue on GitHub\nlist_github_issues\tRetrieve open repository issues\nlist_github_labels\tRetrieve repository labels\ncheck_duplicate_issue\tFind likely duplicate issue candidates\ngenerate_issue\n\nGenerates a structured issue from supplied information.\n\nInputs\ndescription\nreproductionSteps\nexpectedBehavior\nactualBehavior\nenvironment\nadditionalContext\nExample output\n{\n  \"title\": \"Bug: Login button does not work\",\n  \"body\": \"## Description\\n\\nLogin button does not work...\",\n  \"labels\": [\"bug\"]\n}\ncheck_duplicate_issue\n\nRetrieves likely duplicate candidates from the repository.\n\nThe tool performs inexpensive lexical candidate ranking against existing open issues.\n\nThe similarity score is not treated as proof of duplication.\n\nGemini performs the final semantic analysis.\n\nThis keeps the expensive AI reasoning focused on a small candidate set rather than every issue in the repository.\n\nlist_github_issues\n\nRetrieves open GitHub issues while filtering out pull requests.\n\nlist_github_labels\n\nRetrieves labels available in the repository.\n\ncreate_github_issue\n\nCreates the final GitHub issue.\n\nThis tool is intentionally not exposed to the autonomous Gemini agent.\n\nIt is invoked directly by the client only after explicit human approval.\n\n🏗️ Architecture\n                         ┌──────────────────┐\n                         │      User        │\n                         └────────┬─────────┘\n                                  │\n                                  ▼\n                         ┌──────────────────┐\n                         │    CLI Client    │\n                         └────────┬─────────┘\n                                  │\n                                  ▼\n                    ┌──────────────────────────┐\n                    │       MCP Client         │\n                    └────────────┬─────────────┘\n                                 │\n                                 ▼\n                    ┌──────────────────────────┐\n                    │       MCP Server         │\n                    └────────────┬─────────────┘\n                                 │\n              ┌──────────────────┼──────────────────┐\n              │                  │                  │\n              ▼                  ▼                  ▼\n       Duplicate Check     Issue Generation    GitHub Tools\n              │                  │                  │\n              ▼                  ▼                  ▼\n       Candidate Issues    Proposed Issue      GitHub REST API\n              │                  │\n              ▼                  ▼\n       Gemini Semantic      Human Approval\n          Analysis              │\n              │                  │\n         ┌────┴────┐        ┌────┴────┐\n         │         │        │         │\n        Yes        No       No       Yes\n         │         │        │         │\n         ▼         ▼        ▼         ▼\n        Stop    Continue   Stop   Create Issue\n🔑 Core Design Principle\n\nThe most important architectural decision is:\n\nGemini does not have autonomous access to the GitHub write operation.\n\nThe workflow is intentionally divided into controlled phases.\n\nPhase 1\nDuplicate Detection\n        │\n        ▼\nSemantic Analysis\n        │\n        ▼\nPhase 2\nCollect Details\n        │\n        ▼\nPhase 3\nIssue Generation\n        │\n        ▼\nPhase 4\nHuman Approval\n        │\n        ▼\nPhase 5\nGitHub Creation\n\nThis provides a clear human-in-the-loop safety boundary around persistent external side effects.\n\n🔄 Workflow\n\nThe complete workflow is:\n\n1. User describes an issue\n              │\n              ▼\n2. Retrieve duplicate candidates\n              │\n              ▼\n3. Gemini performs semantic analysis\n              │\n       ┌──────┴──────┐\n       │             │\n    Duplicate      No duplicate\n       │             │\n       ▼             ▼\n      Stop    4. Collect additional details\n                     │\n                     ▼\n             5. Gemini generates\n                structured issue\n                     │\n                     ▼\n             6. Display proposed issue\n                     │\n                     ▼\n             7. Ask user for approval\n                     │\n              ┌──────┴──────┐\n              │             │\n             No            Yes\n              │             │\n              ▼             ▼\n             Stop    8. Client creates\n                       GitHub issue\n🔍 Duplicate Detection\n\nDuplicate detection is deliberately split into two stages.\n\nStage 1 — Candidate Retrieval\n\nThe MCP tool performs inexpensive lexical similarity/ranking against existing open issues.\n\nFor example:\n\nUser:\n\n\n\"The search results page crashes when I apply multiple filters.\"\n\n\n                    │\n                    ▼\n\n\n          check_duplicate_issue\n\n\n                    │\n                    ▼\n\n\nCandidate #8\n\n\n\"The search results page crashes\nwhen I apply multiple filters.\"\n\n\nSimilarity: 0.21\n\nThe similarity score is only used to identify potentially relevant candidates.\n\nIt is not considered proof of duplication.\n\nStage 2 — Semantic Analysis\n\nGemini receives the candidate issues and determines whether any candidate describes the same underlying problem.\n\nExample:\n\n{\n  \"isDuplicate\": true,\n  \"duplicateIssue\": {\n    \"number\": 8,\n    \"title\": \"Bug: The search results page crashes when I apply multiple filters.\",\n    \"url\": \"https://github.com/example/repository/issues/8\"\n  },\n  \"reason\": \"The candidate describes the exact same underlying problem.\"\n}\n\nThis prevents unrelated issues from being incorrectly classified as duplicates merely because they share common words such as:\n\nlogin\npage\nbutton\ncrash\nissue\n🤖 Agent Workflow\n\nThe Gemini agent supports controlled multi-step tool execution.\n\nAvailable MCP tools are restricted according to the current workflow phase.\n\nPhase 1 — Duplicate Detection\n\nGemini receives:\n\ncheck_duplicate_issue\n\nThe agent can use this tool to retrieve candidate issues.\n\nIt cannot use:\n\ngenerate_issue\ncreate_github_issue\n\nduring this phase.\n\nPhase 3 — Issue Generation\n\nGemini receives:\n\nlist_github_labels\ngenerate_issue\n\nThis allows the agent to inspect repository labels and generate the proposed issue.\n\nIt still cannot create the GitHub issue.\n\nPhase 5 — Issue Creation\n\nThe autonomous Gemini agent does not receive:\n\ncreate_github_issue\n\nInstead, the application directly invokes the tool after explicit human approval.\n\n🔐 Security Model\n\nThe project uses multiple layers to prevent unintended GitHub writes.\n\n1. Phase-Based Tool Exposure\n\nAvailable tools are restricted depending on the current workflow phase.\n\nDuplicate Phase\n      │\n      └── check_duplicate_issue\nGenerate Phase\n      │\n      ├── list_github_labels\n      └── generate_issue\nCreation Phase\n      │\n      └── create_github_issue\n             (client-controlled)\n2. Autonomous Write Protection\n\nThe Gemini agent cannot directly invoke:\n\ncreate_github_issue\n\nEven if the model attempts to request the tool, the agent workflow rejects the operation.\n\n3. Human Approval\n\nThe proposed issue is displayed to the user before creation.\n\nExample:\n\n================================\nPROPOSED GITHUB ISSUE\n================================\n\n\nTitle:\nBug: Login button does not work with valid credentials.\n\n\nLabels:\nbug\n\n\nBody:\n\n\n## Description\n\n\nLogin button does not work with valid credentials.\n\n\n## Steps to Reproduce\n\n\nOpen login page → enter valid credentials → click Login.\n\n\n## Expected Behavior\n\n\nUser should be redirected to the dashboard.\n\n\n## Actual Behavior\n\n\nNothing happens after clicking Login.\n\n\nCreate this issue on GitHub? [y/N]:\n\nOnly explicit approval proceeds to the GitHub write operation.\n\n👤 Human-in-the-Loop Creation\n\nIssue creation is intentionally controlled by the application.\n\nGemini\n   │\n   ▼\nGenerate Proposed Issue\n   │\n   ▼\nCLI Displays Issue\n   │\n   ▼\nUser Approval\n   │\n   ├── No ──► Stop\n   │\n   └── Yes\n         │\n         ▼\nClient invokes create_github_issue\n         │\n         ▼\nGitHub\n\nCreating a GitHub issue is a persistent external side effect.\n\nTherefore, the AI proposes the action while the user controls the final write operation.\n\n🔄 Gemini Error Handling\n\nThe Gemini client includes retry handling for temporary API failures.\n\nHTTP 429\n\nThe system distinguishes between temporary rate-limit errors and exhausted daily quotas.\n\nTemporary 429 errors are retried according to the configured retry policy.\n\nDaily quota exhaustion is detected separately and is not repeatedly retried because additional requests cannot succeed until the quota resets or a different Gemini project/model is used.\n\nHTTP 5xx\n\nTemporary Gemini server-side failures are retried automatically.\n\nExamples include:\n\n500\n502\n503\n504\nRetry Configuration\n\nRetry behavior can be configured through environment variables:\n\nGEMINI_MAX_RETRIES=3\nGEMINI_RETRY_BASE_DELAY=1000\n\nThe retry delay increases between attempts.\n\nInvalid JSON\n\nIf an MCP tool expected to return JSON produces malformed output, the agent reports a clear error.\n\nExamples:\n\ngenerate_issue returned invalid JSON.\n\nor:\n\ncheck_duplicate_issue returned invalid JSON.\n\nThis keeps failures localized and easier to diagnose.\n\n📚 Use as a Library\n\nGitHub Issue MCP is designed to be embedded into another Node.js application.\n\nCreate an MCP server\nimport {\n  createGitHubIssueMcpServer\n} from \"github-issue-mcp/server\";\n\n\nconst server = createGitHubIssueMcpServer({\n  name: \"my-github-issue-server\",\n  version: \"1.0.0\"\n});\n\nThe server factory has no dependency on a specific transport, allowing the MCP server to be reused by different hosts and transports.\n\nStart a stdio server\nimport {\n  startStdioServer\n} from \"github-issue-mcp/server/stdio\";\n\n\nawait startStdioServer();\nStart the executable CLI\nnpx -y github-issue-mcp\n\nThe executable starts the reusable MCP server using the stdio transport.\n\n📦 Package Exports\n\nThe npm package exposes the following public entry points:\n\ngithub-issue-mcp\ngithub-issue-mcp/server\ngithub-issue-mcp/server/stdio\nServer factory\nimport {\n  createGitHubIssueMcpServer\n} from \"github-issue-mcp/server\";\nStdio server\nimport {\n  startStdioServer\n} from \"github-issue-mcp/server/stdio\";\nCLI\nnpx -y github-issue-mcp\n🌐 MCP Registry\n\nGitHub Issue MCP is published to the official MCP Registry.\n\nRegistry identifier:\n\nio.github.sarim-aliii/github-issue-mcp\n\nnpm package:\n\ngithub-issue-mcp\n\nCurrent release:\n\nv1.1.2\n\nThe Registry publication allows MCP-compatible ecosystems to discover the server using its official registry identity.\n\n🧪 Testing\n\nThe project uses Vitest for automated testing.\n\nThe current test suite contains:\n\n12 test files\n47 tests\n47 passing\n\nTests cover multiple layers of the application.\n\nGitHub API Tests\ntests/github/issues.test.ts\n\nValidates:\n\nGitHub issue retrieval\nPull-request filtering\nLabel retrieval\nLabel validation\nEmpty label handling\nGitHub issue creation\nGitHub API error handling\nMCP Tool Tests\ntests/tools/mcp-tools.test.ts\n\nValidates:\n\nMCP tool registration\nMCP tool invocation\nTool argument handling\nMCP error responses\nIssue Generation Tests\ntests/tools/generate-issue.test.ts\n\nValidates:\n\nBug issue generation\nOptional field handling\nFallback placeholders\nStructured issue output\nDuplicate Detection Tests\ntests/tools/check-duplicate.test.ts\n\nValidates:\n\nCandidate retrieval\nSimilarity ranking\nCandidate limiting\nDuplicate detection behavior\nGemini Agent Tests\ntests/client/agent.test.ts\n\nValidates:\n\nGemini request handling\nTemporary 429 retry behavior\nTemporary 5xx retry behavior\nDaily quota handling\nMaximum retry behavior\nNon-retryable errors\nAgent Workflow Tests\ntests/client/agent-workflow.test.ts\n\nValidates:\n\nDuplicate-check phase restrictions\nIssue-generation phase restrictions\nLabel lookup\nStructured issue generation\nAutonomous creation protection\nMalformed MCP responses\nWorkflow Tests\ntests/client/workflow.test.ts\n\nValidates:\n\nDuplicate workflow termination\nSuccessful issue generation and creation\nApproval rejection\nMissing generated issue handling\nConfiguration Tests\ntests/client/config.test.ts\n\nValidates:\n\nDefault Gemini configuration\nEnvironment-variable configuration\nMCP Integration Tests\ntests/integration/mcp-server.test.ts\n\nValidates:\n\nMCP server startup\nMCP connection behavior\nMCP tool availability\nPackage API Integration Tests\ntests/integration/package-api.test.ts\n\nValidates the public npm package API and ensures the published package exposes the expected reusable server interfaces.\n\nIssue Creation Safety Tests\n\nThe integration suite also validates that the issue creation boundary remains client-controlled and that the autonomous agent cannot bypass the intended approval flow.\n\n▶️ Run Tests\n\nRun the complete test suite:\n\nnpm test\n\nRun TypeScript validation:\n\nnpm run typecheck\n\nBuild the project:\n\nnpm run build\n\nExpected current result:\n\nTest Files  12 passed (12)\nTests       47 passed (47)\n📊 Test Coverage\n\nThe current suite validates:\n\n✓ GitHub API interactions\n✓ Issue listing\n✓ Pull-request filtering\n✓ Label retrieval\n✓ Label validation\n✓ Issue creation\n✓ GitHub API error handling\n✓ MCP tool registration\n✓ MCP tool invocation\n✓ Issue generation\n✓ Duplicate candidate retrieval\n✓ Lexical candidate ranking\n✓ Semantic duplicate workflow\n✓ Gemini retries\n✓ Gemini 429 handling\n✓ Gemini 5xx handling\n✓ Gemini quota handling\n✓ Malformed JSON handling\n✓ Agent phase restrictions\n✓ Human-controlled write boundary\n✓ Workflow orchestration\n✓ Approval handling\n✓ MCP integration\n✓ Package API\n✓ Configuration defaults\n✓ Environment-based configuration\n🧪 Consumer Integration Testing\n\nThe project also validates installation from the built npm package in a clean consumer project.\n\nThe tested flow is:\n\nBuild package\n      │\n      ▼\nnpm pack\n      │\n      ▼\nInstall package in clean project\n      │\n      ▼\nImport public API\n      │\n      ▼\nCreate MCP server\n      │\n      ▼\nStart stdio server\n      │\n      ▼\nConnect with MCP Client\n      │\n      ▼\nDiscover tools\n\nThe published package has been tested using:\n\nnpm install github-issue-mcp\n\nand the executable:\n\nnpx github-issue-mcp\n\nThe consumer integration verifies that the expected MCP tools are available.\n\n🛠️ Tech Stack\nLanguage\nTypeScript\nNode.js\nAI\nGoogle Gemini\n@google/genai\nMCP\n@modelcontextprotocol/sdk\nValidation\nZod\nCLI\nInquirer\nTesting\nVitest\nGitHub\nGitHub REST API\n📁 Project Structure\ngithub-issue-mcp/\n│   │   ├── agent.ts\n│   │   ├── ai-client.ts\n│   │   ├── approval.ts\n│   │   ├── cli.ts\n│   │   ├── config.ts\n│   │   ├── index.ts\n│   │   ├── issue-details.ts\n│   │   ├── logger.ts\n│   │   ├── tool-adapter.ts\n│   │   └── workflow.ts\n│   │\n│   ├── github/\n│   │   ├── client.ts\n│   │   └── issues.ts\n│   │\n│   ├── server/\n│   │   ├── cli.ts\n│   │   ├── create-server.ts\n│   │   ├── index.ts\n│   │   └── stdio.ts\n│   │\n│   ├── tools/\n│   │   ├── check-duplicate.ts\n│   │   ├── create-issue.ts\n│   │   ├── generate-issue.ts\n│   │   ├── list-issues.ts\n│   │   └── list-labels.ts\n│   │\n│   ├── types/\n│   │   └── issue.ts\n│   │\n│   └── index.ts\n│\n├── examples/\n│   ├── basic-server/\n│   │   └── index.mjs\n│   │\n│   ├── stdio-client/\n│   │   └── index.mjs\n│   │\n│   └── README.md\n│\n├── tests/\n│   ├── client/\n│   │   ├── agent.test.ts\n│   │   ├── agent-workflow.test.ts\n│   │   ├── config.test.ts\n│   │   └── workflow.test.ts\n│   │\n│   ├── github/\n│   │   └── issues.test.ts\n│   │\n│   ├── integration/\n│   │   ├── issue-creation-safety.test.ts\n│   │   ├── mcp-server.test.ts\n│   │   └── package-api.test.ts\n│   │\n│   ├── server/\n│   │   └── create-server.test.ts\n│   │\n│   └── tools/\n│       ├── check-duplicate.test.ts\n│       ├── generate-issue.test.ts\n│       └── mcp-tools.test.ts\n│\n├── .env.example\n├── .gitignore\n├── package.json\n├── server.json\n├── tsconfig.json\n└── README.md\n⚙️ Local Development Setup\n1. Clone the repository\ngit clone https://github.com/sarim-aliii/github-issue-mcp.git\ncd github-issue-mcp\n2. Install dependencies\nnpm install\n3. Configure environment variables\n\nCreate a .env file:\n\nGITHUB_TOKEN=your_github_token\nGITHUB_OWNER=your_github_username\nGITHUB_REPO=your_repository\n\n\nGEMINI_API_KEY=your_gemini_api_key\n\n\nGEMINI_MODEL=gemini-3.6-flash\nGEMINI_MAX_RETRIES=3\nGEMINI_RETRY_BASE_DELAY=1000\n\n\nDEBUG=false\n\nNever commit .env to Git.\n\n▶️ Running the Assistant\n\nThe original interactive client can be started with:\n\nnpx tsx src/client/index.ts\n\nThe assistant will ask for a short issue description.\n\nExample:\n\n✔ Describe your issue:\nThe export button on the reports page does nothing when clicked.\n\nThe assistant will then:\n\n1. Connect to the MCP server\n2. Discover available MCP tools\n3. Search for possible duplicates\n4. Analyze candidates semantically\n5. Stop if a duplicate exists\n6. Ask for additional details\n7. Generate a structured issue\n8. Display the proposed issue\n9. Ask for human confirmation\n10. Create the issue if approved\n💡 Example\nInput\nThe export button on the reports page does nothing when clicked.\nAdditional Information\nReproduction\nOpen the reports page, select a report, and click Export.\nExpected\nThe selected report should be downloaded as a CSV file.\nActual\nNothing happens after clicking Export.\nEnvironment\nChrome 126, Windows 11, App v2.4.1.\nAdditional context\nThe issue occurs consistently.\nGenerated Issue\n## Description\n\n\nThe export button on the reports page does nothing when clicked.\n\n\n## Steps to Reproduce\n\n\nOpen the reports page, select a report, and click Export.\n\n\n## Expected Behavior\n\n\nThe selected report should be downloaded as a CSV file.\n\n\n## Actual Behavior\n\n\nNothing happens after clicking the Export button.\n\n\n## Environment\n\n\nChrome 126, Windows 11, App v2.4.1.\n\n\n## Additional Context\n\n\nThe issue occurs consistently.\n\nThe user then sees:\n\nCreate this issue on GitHub? [y/N]:\n\nOnly an explicit approval creates the issue.\n\n🧠 Design Decisions\nWhy MCP?\n\nMCP provides a standardized interface between the AI agent and external capabilities.\n\nInstead of embedding GitHub API logic directly into the Gemini workflow, GitHub operations are exposed as MCP tools.\n\n                 Gemini\n                    │\n                    │ MCP\n                    ▼\n              GitHub Tools\n                    │\n                    ▼\n             GitHub REST API\n\nThis keeps the AI layer separated from external-service logic and makes the tools reusable.\n\nWhy separate duplicate retrieval and semantic analysis?\n\nThe candidate retrieval process is inexpensive and deterministic enough to narrow the search space.\n\nGemini then performs the more expensive semantic reasoning only on relevant candidates.\n\nAll Open Issues\n      │\n      ▼\nLexical Candidate Ranking\n      │\n      ▼\nSmall Candidate Set\n      │\n      ▼\nGemini Semantic Analysis\n      │\n      ▼\nDuplicate / Not Duplicate\n\nThis is more efficient than asking an LLM to reason over every issue in a repository.\n\nWhy require human approval?\n\nCreating a GitHub issue is a persistent external side effect.\n\nThe system therefore separates:\n\nAI Reasoning\n\nfrom:\n\nExternal Write Operation\n\nThe AI proposes the issue while the user controls the final action.\n\nWhy restrict tools by phase?\n\nDifferent workflow stages require different capabilities.\n\nGiving the model access to every tool at every stage increases the possibility of unintended behavior.\n\nInstead:\n\nDuplicate Phase\n       │\n       ▼\ncheck_duplicate_issue\nGenerate Phase\n       │\n       ├── list_github_labels\n       └── generate_issue\nCreation Phase\n       │\n       ▼\ncreate_github_issue\n(client controlled)\n\nThis makes the agent's permissions explicit and easier to reason about.\n\n🛡️ Reliability\n\nThe project includes explicit handling for temporary Gemini failures.\n\nTemporary 429\n     │\n     ▼\nRetry according to policy\nTemporary 5xx\n     │\n     ▼\nRetry according to policy\nDaily quota exhausted\n     │\n     ▼\nStop immediately\n\nThis avoids wasting retry attempts when a daily quota cannot be recovered through another request.\n\n🚧 Future Improvements\n\nPotential future improvements include:\n\nMore sophisticated duplicate-ranking algorithms\nGitHub issue comments\nIssue updates\nIssue assignment\nMilestone support\nGitHub Projects integration\nPull-request creation\nAutomatic issue categorization\nRepository-specific issue templates\nSupport for multiple GitHub repositories\nPersistent conversation context\nStreaming Gemini responses\nMore comprehensive end-to-end integration tests\nStructured logging and observability\nMetrics for agent/tool execution\nRepository-specific issue policies\nAdditional MCP transports\n🎯 Project Goals\n\nThis project demonstrates how to combine:\n\nLLM Reasoning\n      +\nMCP Tool Calling\n      +\nExternal APIs\n      +\nStructured Validation\n      +\nSemantic Duplicate Detection\n      +\nHuman Approval\n      +\nAutomated Testing\n\nThe main goal is not simply to generate GitHub issues with AI.\n\nThe goal is to demonstrate a controlled agentic workflow where:\n\nThe model can reason\nThe model can use tools\nTool access is restricted by workflow phase\nGitHub operations are isolated behind MCP\nDuplicate detection combines deterministic retrieval with AI reasoning\nPersistent writes require explicit human approval\nTemporary AI failures are handled automatically\nThe MCP server can be reused independently of the interactive client\nThe package can be consumed by other Node.js applications\nThe package can be launched directly as an MCP stdio server\nThe workflow is covered by automated tests\n📌 Current Status\nProject\nFunctional\nPackage\ngithub-issue-mcp\nv1.1.2\nMCP Registry\nio.github.sarim-aliii/github-issue-mcp\nTypeScript\n✓ Typecheck passing\n✓ Build passing\nTests\n✓ 12 test files\n✓ 47 tests\n✓ 47 passing\nCore Workflow\n✓ MCP server\n✓ MCP client\n✓ Gemini integration\n✓ Duplicate candidate retrieval\n✓ Semantic duplicate analysis\n✓ Issue generation\n✓ Label retrieval\n✓ Human approval\n✓ GitHub issue creation\nReusable Package\n✓ npm package\n✓ Public server factory\n✓ Public stdio server API\n✓ Executable MCP CLI\n✓ Consumer integration test\n✓ Package API integration test\nSafety\n✓ Phase-restricted Gemini tools\n✓ Autonomous write protection\n✓ Client-controlled GitHub creation\n✓ Human approval boundary\nReliability\n✓ Gemini 429 retry handling\n✓ Gemini 5xx retry handling\n✓ Daily quota detection\n✓ Configurable retry policy\n✓ Invalid JSON handling\n📄 License\n\nThis project is intended as a demonstration and reusable implementation of an AI-powered, MCP-based GitHub issue management workflow.\n\nSee the repository license for licensing terms.\n\n🔗 Links\n\nRepository:\n\nhttps://github.com/sarim-aliii/github-issue-mcp\n\nnpm:\n\nhttps://www.npmjs.com/package/github-issue-mcp\n\nMCP Registry:\n\nhttps://registry.modelcontextprotocol.io/",
  "bytes": 26582,
  "sha": "2fcd9823fe5b74da23617f6673289adc56f5e81e1b7ba98c530ce047fbb16ae4",
  "repo_slug": "sarim-aliii/github-issue-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sarim_aliii_github_issue_mcp_ad627c46/readme"
}