{"_id":"@iflow-mcp/vooster-ai-github-fetcher-mcp","name":"@iflow-mcp/vooster-ai-github-fetcher-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@iflow-mcp/vooster-ai-github-fetcher-mcp","version":"1.1.0","description":"MCP server for fetching GitHub repository files and directory trees","main":"dist/server.js","type":"module","bin":{"github-fetcher-mcp":"dist/server.js"},"scripts":{"prebuild":"rimraf dist","build":"tsc","start":"node dist/server.js","dev":"tsx src/server.ts","test":"NODE_OPTIONS=--experimental-vm-modules jest","test:watch":"NODE_OPTIONS=--experimental-vm-modules jest --watch","test:coverage":"NODE_OPTIONS=--experimental-vm-modules jest --coverage","typecheck":"tsc --noEmit","lint":"eslint src tests --ext .ts","lint:fix":"eslint src tests --ext .ts --fix","prepublishOnly":"npm run lint && npm run typecheck && npm run build && npm test"},"keywords":["mcp","github","fetcher","modelcontextprotocol","repository","code-analysis"],"author":{"name":"choesumin"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/choesumin/github-fetcher-mcp.git"},"bugs":{"url":"https://github.com/choesumin/github-fetcher-mcp/issues"},"homepage":"https://github.com/choesumin/github-fetcher-mcp#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","commander":"^14.0.1","zod":"^3.22.4"},"devDependencies":{"@types/jest":"^29.5.11","@types/node":"^20.10.6","@typescript-eslint/eslint-plugin":"^6.17.0","@typescript-eslint/parser":"^6.17.0","eslint":"^8.56.0","jest":"^29.7.0","rimraf":"^6.0.1","ts-jest":"^29.1.1","tsx":"^4.7.0","typescript":"^5.3.3"},"_id":"@iflow-mcp/vooster-ai-github-fetcher-mcp@1.1.0","gitHead":"a712eaedfef3b4784e80b560c8a00524a9cf6755","types":"./dist/server.d.ts","_nodeVersion":"24.8.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-hA2jkqRTPX5GZb/bbNrhmYQ3Q7e73neNrP7WcoQBKJawU593tzec7L5e5DjXPtlfJnB3EPUgy7qEV6abOTo7xg==","shasum":"ca4719824c00326f3e94593092780029894dd61c","tarball":"https://registry.npmjs.org/@iflow-mcp/vooster-ai-github-fetcher-mcp/-/vooster-ai-github-fetcher-mcp-1.1.0.tgz","fileCount":43,"unpackedSize":89688,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDo1tes9r0Xye/cnv6tL3A5c8L7RVgn2I8qsB8gwPf7TQIgTsPWT7ZzhrM/57kZVRF//R6AM6MPJf/PbmgeQGn0ZC8="}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vooster-ai-github-fetcher-mcp_1.1.0_1767750108272_0.9198551525382344"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-07T01:41:48.154Z","1.1.0":"2026-01-07T01:41:48.412Z","modified":"2026-01-07T01:41:48.709Z"},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"description":"MCP server for fetching GitHub repository files and directory trees","homepage":"https://github.com/choesumin/github-fetcher-mcp#readme","keywords":["mcp","github","fetcher","modelcontextprotocol","repository","code-analysis"],"repository":{"type":"git","url":"git+https://github.com/choesumin/github-fetcher-mcp.git"},"author":{"name":"choesumin"},"bugs":{"url":"https://github.com/choesumin/github-fetcher-mcp/issues"},"license":"MIT","readme":"# GitHub Fetcher MCP\n\n[![npm version](https://badge.fury.io/js/github-fetcher-mcp.svg)](https://www.npmjs.com/package/github-fetcher-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)\n[![Tests](https://img.shields.io/badge/tests-79%20passed-success)](https://github.com/choesumin/github-fetcher-mcp)\n\nMCP (Model Context Protocol) server for fetching GitHub repository files and directory trees.\n\n## Features\n\n- **fetch-file**: Fetch raw file content from GitHub repositories\n- **fetch-subdir-tree**: Fetch directory tree structure in unix tree format\n- **fetch-sub-tree** ⭐ NEW: Enhanced directory tree with file sizes, depth limits, statistics, and filtering\n- Flexible configuration via CLI arguments or per-request parameters\n- Built with TypeScript for type safety\n- Comprehensive test coverage (79 tests)\n\n## Installation\n\n### NPM\n\n```bash\nnpm install -g github-fetcher-mcp\n```\n\n### Smithery\n\nTo install GitHub Fetcher MCP Server for any client automatically via [Smithery](https://smithery.ai):\n\n```bash\nnpx -y @smithery/cli@latest install github-fetcher-mcp --client <CLIENT_NAME>\n```\n\nAvailable clients: `cursor`, `claude`, `vscode`, `windsurf`, `cline`, `zed`, etc.\n\n**Example for Cursor:**\n\n```bash\nnpx -y @smithery/cli@latest install github-fetcher-mcp --client cursor\n```\n\nThis will automatically configure the MCP server in your chosen client.\n\n## MCP Client Integration\n\nGitHub Fetcher MCP can be integrated with various AI coding assistants and IDEs that support the Model Context Protocol (MCP).\n\n### Requirements\n\n- Node.js >= v18.0.0\n- An MCP-compatible client (Cursor, Claude Code, VS Code, Windsurf, etc.)\n\n<details>\n<summary><b>Install in Cursor</b></summary>\n\nGo to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`\n\nAdd the following configuration to your `~/.cursor/mcp.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n**Without repoIdentifier** (specify repository per request):\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Claude Code</b></summary>\n\nRun this command:\n\n```sh\nclaude mcp add github-fetcher -- npx -y github-fetcher-mcp --repoIdentifier facebook/react/main\n```\n\nOr without repoIdentifier:\n\n```sh\nclaude mcp add github-fetcher -- npx -y github-fetcher-mcp\n```\n\n</details>\n\n<details>\n<summary><b>Install in VS Code</b></summary>\n\nAdd this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.\n\n```json\n\"mcp\": {\n  \"servers\": {\n    \"github-fetcher\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Windsurf</b></summary>\n\nAdd this to your Windsurf MCP config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Cline</b></summary>\n\n1. Open **Cline**\n2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section\n3. Choose **Remote Servers** tab\n4. Click the **Edit Configuration** button\n5. Add github-fetcher to `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Claude Desktop</b></summary>\n\nOpen Claude Desktop developer settings and edit your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Zed</b></summary>\n\nAdd this to your Zed `settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"github-fetcher\": {\n      \"source\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Roo Code</b></summary>\n\nAdd this to your Roo Code MCP configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Using with Bun</b></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Using with Docker</b></summary>\n\n**Build the Docker Image:**\n\nCreate a `Dockerfile`:\n\n```dockerfile\nFROM node:18-alpine\n\nWORKDIR /app\n\n# Install the package globally\nRUN npm install -g github-fetcher-mcp\n\n# Expose the server port\nEXPOSE 3000\n\n# Default command to run the server\nCMD [\"github-fetcher-mcp\"]\n```\n\nBuild the image:\n\n```bash\ndocker build -t github-fetcher-mcp .\n```\n\n**Configure Your MCP Client:**\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-p\", \"3000:3000\", \"github-fetcher-mcp\", \"--repoIdentifier\", \"facebook/react/main\"]\n    }\n  }\n}\n```\n\n</details>\n\n## Usage\n\n### With Repository Identifier (CLI Argument)\n\nWhen you provide a `--repoIdentifier` argument, all tools will use that repository by default:\n\n```bash\ngithub-fetcher-mcp --repoIdentifier facebook/react/main\n```\n\n**Tools available:**\n- `fetch-file`: Requires only `filePath`\n- `fetch-subdir-tree`: Requires only `dirPath`\n- `fetch-sub-tree`: Requires only `dirPath` (+ optional: `showSize`, `maxDepth`, `showStats`, `fileExtFilter`)\n\n### Without Repository Identifier\n\nWhen no repository identifier is provided, you can specify the repository for each request:\n\n```bash\ngithub-fetcher-mcp\n```\n\n**Tools available:**\n- `fetch-file`: Requires `ownerName`, `repoName`, `branchName` (optional, default: 'main'), and `filePath`\n- `fetch-subdir-tree`: Requires `ownerName`, `repoName`, `branchName` (optional, default: 'main'), and `dirPath`\n- `fetch-sub-tree`: Requires `ownerName`, `repoName`, `branchName` (optional, default: 'main'), `dirPath` (+ optional: `showSize`, `maxDepth`, `showStats`, `fileExtFilter`)\n\n## Available Tools\n\nGitHub Fetcher MCP provides the following tools that can be used by LLMs:\n\n- **fetch-file**: Fetches the raw content of a file from a GitHub repository\n  - Required parameters vary based on whether `--repoIdentifier` is provided\n  - Returns the complete file content as text\n\n- **fetch-subdir-tree**: Fetches directory tree structure in unix tree format\n  - Required parameters vary based on whether `--repoIdentifier` is provided\n  - Returns formatted directory tree showing files and subdirectories\n\n- **fetch-sub-tree** ⭐ NEW: Enhanced version with advanced options\n  - Required parameters vary based on whether `--repoIdentifier` is provided\n  - Optional parameters:\n    - `showSize` (boolean): Show file and directory sizes\n    - `maxDepth` (number): Limit tree depth (e.g., 1 for immediate children only)\n    - `showStats` (boolean): Show statistics summary (default: true)\n    - `fileExtFilter` (string[]): Filter files by extensions (e.g., [\".ts\", \".js\"])\n  - Returns enhanced directory tree with optional file sizes and statistics\n\n## Usage Examples\n\n### Example 1: Fetch a specific file\n\n**In Cursor/Claude Code:**\n```\nFetch the package.json file from the facebook/react repository on the main branch\n```\n\n**In any MCP client (with repoIdentifier configured):**\n```\nShow me the contents of src/index.ts\n```\n\n### Example 2: Browse directory structure\n\n**In Cursor/Claude Code:**\n```\nShow me the directory structure of the src folder in microsoft/vscode on the main branch\n```\n\n**In any MCP client (with repoIdentifier configured):**\n```\nWhat files are in the components directory?\n```\n\n### Example 3: Analyze code structure\n\n**In Cursor/Claude Code:**\n```\nI want to understand the structure of the Next.js repository.\nShow me the directory tree of the packages folder from vercel/next.js on the canary branch.\nThen fetch the package.json file to see the dependencies.\n```\n\n## Tool Reference\n\n### fetch-file\n\nFetches the raw content of a file from a GitHub repository.\n\n**With repoIdentifier:**\n```json\n{\n  \"filePath\": \"src/index.ts\"\n}\n```\n\n**Without repoIdentifier:**\n```json\n{\n  \"ownerName\": \"facebook\",\n  \"repoName\": \"react\",\n  \"branchName\": \"main\",\n  \"filePath\": \"src/index.ts\"\n}\n```\n\n### fetch-subdir-tree\n\nFetches directory tree structure in unix tree format.\n\n**With repoIdentifier:**\n```json\n{\n  \"dirPath\": \"src\"\n}\n```\n\n**Without repoIdentifier:**\n```json\n{\n  \"ownerName\": \"microsoft\",\n  \"repoName\": \"vscode\",\n  \"branchName\": \"main\",\n  \"dirPath\": \"src\"\n}\n```\n\n### fetch-sub-tree ⭐ NEW\n\nEnhanced directory tree with file sizes, depth limits, and filtering options.\n\n**With repoIdentifier - Basic usage:**\n```json\n{\n  \"dirPath\": \"src\"\n}\n```\n\n**With repoIdentifier - Show file sizes:**\n```json\n{\n  \"dirPath\": \"src\",\n  \"showSize\": true\n}\n```\n\n**With repoIdentifier - Limit depth:**\n```json\n{\n  \"dirPath\": \"src\",\n  \"maxDepth\": 2\n}\n```\n\n**With repoIdentifier - Filter by file extensions:**\n```json\n{\n  \"dirPath\": \"src\",\n  \"fileExtFilter\": [\".ts\", \".tsx\"]\n}\n```\n\n**With repoIdentifier - All options:**\n```json\n{\n  \"dirPath\": \"src\",\n  \"showSize\": true,\n  \"maxDepth\": 3,\n  \"showStats\": true,\n  \"fileExtFilter\": [\".ts\", \".js\"]\n}\n```\n\n**Example Output (with showSize and showStats):**\n```\nsrc/\n├── components/ (2 files, 15.3KB)\n│   ├── Button.tsx (8.2KB)\n│   └── Input.tsx (7.1KB)\n└── utils/ (3 files, 5.8KB)\n    ├── helpers.ts (2.1KB)\n    ├── format.ts (1.9KB)\n    └── validate.ts (1.8KB)\n\n📊 Summary: 2 directories, 5 files, 21.1KB total\n```\n\n**Without repoIdentifier:**\n```json\n{\n  \"ownerName\": \"microsoft\",\n  \"repoName\": \"vscode\",\n  \"branchName\": \"main\",\n  \"dirPath\": \"src\",\n  \"showSize\": true,\n  \"maxDepth\": 2\n}\n```\n\n## Docker Usage\n\n### Build Docker Image\n\n```bash\ndocker build -t github-fetcher-mcp .\n```\n\n### Run with Docker\n\n**With repoIdentifier:**\n\n```bash\ndocker run -d -p 3000:3000 \\\n  --name github-fetcher \\\n  github-fetcher-mcp \\\n  node dist/server.js --repoIdentifier facebook/react/main\n```\n\n**Without repoIdentifier:**\n\n```bash\ndocker run -d -p 3000:3000 \\\n  --name github-fetcher \\\n  github-fetcher-mcp\n```\n\n### Docker Compose Example\n\nCreate a `docker-compose.yml`:\n\n```yaml\nversion: '3.8'\n\nservices:\n  github-fetcher-mcp:\n    build: .\n    ports:\n      - \"3000:3000\"\n    environment:\n      - PORT=3000\n      - NODE_ENV=production\n    command: [\"node\", \"dist/server.js\", \"--repoIdentifier\", \"facebook/react/main\"]\n    restart: unless-stopped\n    healthcheck:\n      test: [\"CMD\", \"node\", \"-e\", \"require('http').get('http://localhost:3000/mcp', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})\"]\n      interval: 30s\n      timeout: 3s\n      retries: 3\n      start_period: 5s\n```\n\nRun with Docker Compose:\n\n```bash\ndocker-compose up -d\n```\n\n### Use Docker Image in MCP Clients\n\nConfigure your MCP client to use the Docker container:\n\n```json\n{\n  \"mcpServers\": {\n    \"github-fetcher\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"github-fetcher-mcp\",\n        \"node\",\n        \"dist/server.js\",\n        \"--repoIdentifier\",\n        \"facebook/react/main\"\n      ]\n    }\n  }\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode\nnpm run dev\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n\n# Lint\nnpm run lint\n```\n\n## Architecture\n\nThe project follows a modular architecture:\n\n- **config/**: CLI argument parsing\n- **services/**: GitHub API integration and tree formatting\n- **tools/**: MCP tool implementations\n- **types/**: TypeScript type definitions\n- **utils/**: Utility functions\n\n## Testing\n\nThe project has comprehensive test coverage:\n- Unit tests for all services, tools, and utilities\n- Integration tests for tool creation\n- 79 total tests, all passing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Generate coverage report\nnpm run test:coverage\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Author\n\nchoesumin\n","readmeFilename":"README.md","_rev":"1-ba5a88e58d2724b0923a59a71ef0f15e"}