mcp-gitpro

🇬🇧 English | 🇹🇷 Turkce

✨ A production-ready, stdio-first GitHub MCP server built on @vaur94/mcpbase.

mcp-gitpro gives AI agents a compact GitHub tool surface without drifting into local git, filesystem mutation, shell execution, or browser automation. The goal is simple: high-value GitHub workflows, low context waste, and clear safety boundaries.

✨ Why mcp-gitpro

• GitHub-focused tool surface for repositories, issues, pull requests, search, and Actions
• Read-only mode, toolset allowlists, and exact-tool allowlists to reduce token waste
• Strict TypeScript, stdio-first runtime, protocol tests, and release automation
• Bilingual documentation with clearly separated English and Turkish doc trees
• Built on the published @vaur94/mcpbase package instead of a local fork

📦 Installation

Requirements

• Node.js >=22.14.0
• npm >=10
• A GitHub token available as MCP_GITPRO_GITHUB_TOKEN

Local install script

bash ./scripts/install-local.sh

The script installs dependencies, builds the server, and runs the test suite.

Manual setup

npm install
npm run build
npm test

Use mcp-gitpro.config.json for repo defaults and behavior flags, and keep secrets out of source control.

⚡ Quick Start

Minimal local launch

export MCP_GITPRO_GITHUB_TOKEN=YOUR_GITHUB_TOKEN
node ./dist/index.js --config ./mcp-gitpro.config.json

Quality gate before connecting a host

npm run ci:check

Common stdio values across hosts

• launcher: node
• entrypoint: /absolute/path/to/mcp-gitpro/dist/index.js
• config flag: --config /absolute/path/to/mcp-gitpro/mcp-gitpro.config.json
• token: MCP_GITPRO_GITHUB_TOKEN=...
• protocol rule: stdout is reserved for MCP; logs belong on stderr

🔌 Integration Guides

Host	Integration model	Guide
OpenCode	opencode.json local MCP entry with command array	OpenCode
Codex CLI / IDE	config.toml with [mcp_servers.<name>]	Codex
VS Code	workspace MCP JSON with command, args, and env	VS Code
Antigravity	mcpServers JSON entry with absolute executable paths	Antigravity

🧰 Tool Surface

Toolsets

• context
• repos
• search
• issues
• pull_requests
• actions

Tools

• github_context
• repository_read
• repository_compare
• search_github
• issue_read
• issue_write
• pull_request_read
• pull_request_write
• actions_read
• actions_write

⚙️ Configuration

Configuration precedence:

1. built-in defaults
2. mcp-gitpro.config.json
3. MCP_GITPRO_* environment variables
4. CLI flags handled by mcpbase

Important fields:

• auth.githubToken
• defaults.owner
• defaults.repo
• defaults.apiBaseUrl
• context.readOnly
• context.toolsets
• context.tools
• output.pageSize
• output.maxFileLines
• output.maxDiffLines
• output.maxBodyChars

🏗️ Project Shape

mcp-gitpro/
|- src/
|  |- config/
|  |- core/
|  |- github/
|  |- shared/
|  |- tools/
|- tests/
|  |- unit/
|  |- protocol/
|- docs/
|  |- en/
|  |- tr/
|- scripts/

🔗 mcpbase Integration

• mcp-gitpro depends on the published @vaur94/mcpbase package from npm
• startup is wired with ApplicationRuntime, createMcpServer, and startStdioServer
• config loading extends mcpbase through createRuntimeConfigSchema and loadConfig
• execution context extends BaseToolExecutionContext with GitHubClient
• streamable HTTP and telemetry remain intentionally unused in this GitHub-specific stdio product

📚 Documentation

• English docs index: docs/en/README.md
• Turkish docs index: docs/tr/README.md
• English configuration: docs/en/configuration.md
• Turkish configuration: docs/tr/configuration.md
• Security policy: .github/SECURITY.md

🧪 Quality Gates

npm run build
npm run typecheck
npm run test
npm run test:coverage
npm run test:protocol
npm run ci:check

🛡️ Scope and Non-goals

This repository intentionally excludes:

• local git CLI workflows
• filesystem editing or patch application
• shell execution
• browser automation
• HTTP transport in v1

Security controls include token-based auth, read-only mode, tool allowlists, output caps, and out-of-band Actions log delivery.

📄 License

MIT - see LICENSE.