{"_id":"@descoped/mcp-pkg-local","_rev":"2-7fcb77ab14fe5966bfb4c8293968fed5","name":"@descoped/mcp-pkg-local","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@descoped/mcp-pkg-local","version":"0.1.0","keywords":["mcp","model-context-protocol","llm","ai","claude","packages","python","source-code"],"author":{"name":"Descoped"},"license":"MIT","_id":"@descoped/mcp-pkg-local@0.1.0","maintainers":[{"name":"overanheim","email":"oranheim@gmail.com"}],"homepage":"https://github.com/descoped/mcp-pkg-local#readme","bugs":{"url":"https://github.com/descoped/mcp-pkg-local/issues"},"bin":{"mcp-pkg-local":"dist/index.js"},"dist":{"shasum":"c9461de0bbb57fd366e00d0de69da6e4be66221e","tarball":"https://registry.npmjs.org/@descoped/mcp-pkg-local/-/mcp-pkg-local-0.1.0.tgz","fileCount":47,"integrity":"sha512-ABjdYLIpd9HgKn42Wf6UVgc/xqJKmUNer7ApP6rKVvtfB+82A7nG/lzOK2r6QhDPDY6nLncW++dpqI/5pEp9yg==","signatures":[{"sig":"MEYCIQDejAUZkVUPkdyPy99mC6nUa37upRa6H+lswcQw21v48gIhAKwWhDOKAUnQwv6KuZFdAWhCgyKx4R52o8+NSBpEByXo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@descoped%2fmcp-pkg-local@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":118469},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"c9237a576632b132760dc3a326b2ff87ae011dd7","imports":{"#types":{"default":"./dist/types.js","development":"./src/types.ts"},"#server":{"default":"./dist/server.js","development":"./src/server.ts"},"#tools/*":{"default":"./dist/tools/*.js","development":"./src/tools/*.ts"},"#utils/*":{"default":"./dist/utils/*.js","development":"./src/utils/*.ts"},"#scanners/*":{"default":"./dist/scanners/*.js","development":"./src/scanners/*.ts"}},"scripts":{"dev":"tsx watch src/index.ts","lint":"eslint . --ext .ts","test":"vitest","build":"tsx scripts/build.ts","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","prepare":"npm run build","test:ui":"vitest --ui","typecheck":"tsc --noEmit","build:verify":"npm run build && node -e \"const fs=require('fs'); if(fs.existsSync('dist/CLAUDE.md')||fs.existsSync('dist/ai_docs')) throw new Error('Build should exclude CLAUDE.md and ai_docs')\"","test:coverage":"vitest run --coverage","prepublishOnly":"npm run test && npm run lint"},"_npmUser":{"name":"overanheim","email":"oranheim@gmail.com"},"repository":{"url":"git+https://github.com/descoped/mcp-pkg-local.git","type":"git"},"_npmVersion":"10.8.2","description":"An MCP tool that scans and indexes local dependency source code, enabling LLMs to understand locally installed package contracts","directories":{},"_nodeVersion":"20.19.4","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.17.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.4","eslint":"^9.33.0","vitest":"^3.2.4","esbuild":"^0.25.9","prettier":"^3.6.2","tsc-alias":"^1.8.16","@vitest/ui":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.3.0","tsconfig-paths":"^4.2.0","@vitest/coverage-v8":"^3.2.4","@typescript-eslint/parser":"^8.39.1","@typescript-eslint/eslint-plugin":"^8.39.1"},"_npmOperationalInternal":{"tmp":"tmp/mcp-pkg-local_0.1.0_1755267195099_0.11440845033298719","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@descoped/mcp-pkg-local","version":"0.1.1","description":"An MCP tool that scans and indexes local dependency source code, enabling LLMs to understand locally installed package contracts","type":"module","main":"./dist/index.js","bin":{"mcp-pkg-local":"dist/index.js"},"imports":{"#server":{"development":"./src/server.ts","default":"./dist/server.js"},"#types":{"development":"./src/types.ts","default":"./dist/types.js"},"#scanners/*":{"development":"./src/scanners/*.ts","default":"./dist/scanners/*.js"},"#tools/*":{"development":"./src/tools/*.ts","default":"./dist/tools/*.js"},"#utils/*":{"development":"./src/utils/*.ts","default":"./dist/utils/*.js"}},"scripts":{"build":"tsx scripts/build.ts","build:verify":"npm run build && node -e \"const fs=require('fs'); if(fs.existsSync('dist/CLAUDE.md')||fs.existsSync('dist/ai_docs')) throw new Error('Build should exclude CLAUDE.md and ai_docs')\"","start":"node dist/index.js","dev":"tsx watch src/index.ts","test":"vitest","test:ui":"vitest --ui","test:coverage":"vitest run --coverage","lint":"eslint . --ext .ts","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","typecheck":"tsc --noEmit","clean":"rm -rf dist node_modules .pkg-local-cache .pkg-local-cache.db .pkg-local-index.json coverage .nyc_output","clean:cache":"rm -rf .pkg-local-cache .pkg-local-cache.db .pkg-local-index.json","prepare":"npm run build","prepublishOnly":"npm run test && npm run lint"},"engines":{"node":">=20.0.0"},"repository":{"type":"git","url":"git+https://github.com/descoped/mcp-pkg-local.git"},"keywords":["mcp","model-context-protocol","llm","ai","claude","packages","python","source-code"],"author":{"name":"Descoped"},"license":"MIT","bugs":{"url":"https://github.com/descoped/mcp-pkg-local/issues"},"homepage":"https://github.com/descoped/mcp-pkg-local#readme","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.3","better-sqlite3":"^12.1.0","msgpackr":"^1.11.5","zod":"^3.25.76"},"devDependencies":{"@types/better-sqlite3":"^7.6.12","@types/node":"^24.3.0","@typescript-eslint/eslint-plugin":"^8.39.1","@typescript-eslint/parser":"^8.39.1","@vitest/coverage-v8":"^3.2.4","@vitest/ui":"^3.2.4","esbuild":"^0.25.9","eslint":"^9.33.0","prettier":"^3.6.2","tsc-alias":"^1.8.16","tsconfig-paths":"^4.2.0","tsx":"^4.20.4","typescript":"^5.9.2","vitest":"^3.2.4"},"_id":"@descoped/mcp-pkg-local@0.1.1","gitHead":"be9e6fe471bd66d1fe2821034d345230d9cf6a32","types":"./dist/index.d.ts","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-ykqyHegLJ5hjMEZvmdsDZkYFSsLimIzNlrqbBF60qxxsUun6PZd3XZZGr0RHi6AXMESa21okOrKFe/2GlSF0yw==","shasum":"efab1316562655a44eb5184b2d278e407309d519","tarball":"https://registry.npmjs.org/@descoped/mcp-pkg-local/-/mcp-pkg-local-0.1.1.tgz","fileCount":64,"unpackedSize":238402,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@descoped%2fmcp-pkg-local@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCBfjBqpyCEeVt9FkHMZbdhRh+YTE+58NDdFjkWl0rSjgIgMd2DFRYBLF4gf0F3tM3yIuXjQP9gZiykoVCc5/v/fX4="}]},"_npmUser":{"name":"overanheim","email":"oranheim@gmail.com"},"directories":{},"maintainers":[{"name":"overanheim","email":"oranheim@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-pkg-local_0.1.1_1755291916692_0.7695597249745239"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-15T14:13:15.031Z","modified":"2025-08-15T21:05:17.260Z","0.1.0":"2025-08-15T14:13:15.255Z","0.1.1":"2025-08-15T21:05:16.896Z"},"bugs":{"url":"https://github.com/descoped/mcp-pkg-local/issues"},"author":{"name":"Descoped"},"license":"MIT","homepage":"https://github.com/descoped/mcp-pkg-local#readme","keywords":["mcp","model-context-protocol","llm","ai","claude","packages","python","source-code"],"repository":{"type":"git","url":"git+https://github.com/descoped/mcp-pkg-local.git"},"description":"An MCP tool that scans and indexes local dependency source code, enabling LLMs to understand locally installed package contracts","maintainers":[{"name":"overanheim","email":"oranheim@gmail.com"}],"readme":"# mcp-pkg-local\n\n[![CI](https://github.com/descoped/mcp-pkg-local/actions/workflows/ci.yml/badge.svg)](https://github.com/descoped/mcp-pkg-local/actions/workflows/ci.yml)\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![MCP Tool](https://img.shields.io/badge/MCP-Tool-green.svg)](https://modelcontextprotocol.io)\n[![Node.js](https://img.shields.io/badge/Node.js-20%2B-brightgreen.svg)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-blue.svg)](https://www.typescriptlang.org)\n[![npm version](https://img.shields.io/npm/v/@descoped/mcp-pkg-local.svg)](https://www.npmjs.com/package/@descoped/mcp-pkg-local)\n\nAn MCP (Model Context Protocol) server that enables LLMs to read and understand locally installed package source code, helping reduce API hallucinations by providing direct access to actual installed packages.\n\n## Features\n\n### Core Capabilities\n- 🔍 **Auto-Detection**: Automatically detects Python or Node.js projects\n- 📖 **Source Code Access**: Direct reading of actual installed package source code\n- ⚡ **High Performance**: SQLite cache with 40x faster validity checks (v0.1.1)\n- 🎯 **Zero Configuration**: Works immediately with standard project structures\n\n### Advanced Filtering\n- 📊 **Summary Mode**: Get package counts with 99% token reduction\n- 🔎 **Regex Filtering**: Filter packages by pattern matching\n- 📦 **Category Filtering**: Separate production/development dependencies (Node.js)\n- 🏷️ **Group Filtering**: Pre-defined groups (testing, linting, building, etc.)\n- 🎚️ **Smart Limits**: Default 50 packages to optimize LLM token usage\n- 🚫 **Type Exclusion**: Optionally exclude @types packages\n\n### Language Support\n- 📦 **Node.js**: Full support with dependency categorization\n  - Package managers: npm, pnpm, yarn, bun\n  - Production vs development classification\n  - Scoped packages (@org/package)\n- 🐍 **Python**: Basic support for virtual environments\n  - Package managers: pip, poetry, uv, pipenv (detection only)\n  - Virtual environments: venv, .venv\n  - Note: Dependency categorization pending\n\n### Performance Optimizations\n- 💾 **SQLite Cache**: High-performance cache with WAL mode for concurrent access\n- 📈 **Relevance Scoring**: Prioritizes direct dependencies (Node.js)\n- 🌲 **Lazy Loading**: File trees loaded on-demand\n- ⏱️ **Fast Operations**: ~150ms scan, ~10ms read, ~5ms cache hits\n- 🚀 **40x Faster**: Validity checks in 0.03ms vs 1.2ms (old JSON cache)\n\n### Developer Experience\n- 🛠️ **TypeScript 5.9+**: Strict mode with full type safety\n- 📦 **ES Modules**: Modern JavaScript with import maps\n- 🧪 **Comprehensive Testing**: 59 tests covering all scenarios\n- 🔒 **Security**: Path sanitization, file size limits, read-only access\n- 🚀 **MCP SDK**: Latest Model Context Protocol implementation\n\n## Why mcp-pkg-local?\n\nLLMs often hallucinate APIs or use outdated syntax from their training data. This tool solves that by letting LLMs read the actual source code of packages installed in your environment, ensuring generated code matches your exact package versions.\n\n## Installation\n\n### Global Installation (Recommended)\n\n```bash\nnpm install -g @descoped/mcp-pkg-local\n```\n\n### Or use directly with npx\n\n```bash\nnpx @descoped/mcp-pkg-local\n```\n\n## MCP Client Configuration\n\n### CLI-Based Code Assistants\n\n#### Claude Code (claude.ai)\n\nCreate `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"@descoped/mcp-pkg-local\"],\n      \"env\": {\n        \"DEBUG\": \"mcp-pkg-local:*\"\n      }\n    }\n  }\n}\n```\n\nOr use the CLI:\n```bash\nclaude mcp add pkg-local -- npx @descoped/mcp-pkg-local\n```\n\nFor local development/testing with the built version:\n```json\n{\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-pkg-local/dist/index.js\"],\n      \"env\": {\n        \"DEBUG\": \"mcp-pkg-local:*\"\n      }\n    }\n  }\n}\n```\n\n#### Gemini CLI\n\nCreate or edit `~/.config/gemini/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"@descoped/mcp-pkg-local\"]\n    }\n  }\n}\n```\n\nAfter adding, use `/mcp list` in Gemini CLI to verify the server is configured.\n\n#### Cursor\n\nCreate `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@descoped/mcp-pkg-local\"],\n      \"cwd\": \"${workspaceFolder}\"\n    }\n  }\n}\n```\n\nOpen Cursor Settings → MCP to verify connection (green status).\n\n### VS Code Extensions\n\n#### Continue Extension\n\nAdd to `.continue/config.json`:\n\n```json\n{\n  \"models\": [...],\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"@descoped/mcp-pkg-local\"],\n      \"cwd\": \"${workspaceFolder}\"\n    }\n  }\n}\n```\n\n#### Windsurf\n\nCreate `.windsurf/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@descoped/mcp-pkg-local\"]\n    }\n  }\n}\n```\n\n### Desktop Applications\n\n#### Claude Desktop\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"pkg-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@descoped/mcp-pkg-local\"]\n    }\n  }\n}\n```\n\nAfter adding, restart Claude Desktop completely. You'll see the MCP indicator (🔌) in the conversation input box.\n\n## Usage\n\nOnce configured, the MCP server provides two main tools:\n\n### 1. scan-packages\n\nScans and indexes all packages in your environment with powerful filtering options:\n\n#### Basic Usage\n```javascript\n// Scan with default settings (returns 50 packages)\nscan-packages\n\n// Force refresh the cache\nscan-packages --forceRefresh\n```\n\n#### Advanced Filtering (v0.1.1+)\n```javascript\n// Get summary only (token-efficient)\nscan-packages --summary\n// Returns: { total: 304, languages: { javascript: 304 }, categories: { production: 12, development: 292 } }\n\n// Filter by regex pattern\nscan-packages --filter \"^react\"  // All React packages\nscan-packages --filter \"eslint\"  // Packages containing 'eslint'\n\n// Filter by category\nscan-packages --category production  // Production dependencies only\nscan-packages --category development // Dev dependencies only\n\n// Filter by predefined groups\nscan-packages --group testing   // Testing tools (jest, mocha, vitest, etc.)\nscan-packages --group building  // Build tools (webpack, vite, rollup, etc.)\nscan-packages --group linting   // Linters (eslint, prettier, etc.)\nscan-packages --group typescript // TypeScript-related packages\n\n// Exclude @types packages\nscan-packages --includeTypes false\n\n// Limit results\nscan-packages --limit 10  // Return only 10 packages\n```\n\n### 2. read-package\n\nRead source files from installed packages with lazy loading for efficiency:\n\n#### Basic Usage\n```javascript\n// Get main files only (default - very efficient)\nread-package express\n// Returns: mainFiles, fileCount, package.json content\n\n// Read specific file\nread-package express lib/router/index.js\n```\n\n#### Advanced Options (v0.1.1+)\n```javascript\n// Get full file tree\nread-package express --includeTree\n\n// Limit tree depth\nread-package express --includeTree --maxDepth 2\n\n// Filter files by pattern\nread-package typescript --includeTree --pattern \"*.d.ts\"\nread-package express --includeTree --pattern \"lib/**\"\n```\n\n## Performance Features (v0.1.1)\n\nThe tool has been optimized for LLM token consumption:\n\n### Token Usage Comparison\n\n| Operation | v0.1.0 | v0.1.1 | Reduction |\n|-----------|--------|--------|-----------|\n| Full scan (all packages) | 20,000 | 2,000 | 90% |\n| Summary scan | N/A | 200 | 99% |\n| Filtered scan (e.g., testing tools) | 20,000 | 500 | 97.5% |\n| Read package (default) | 5,000 | 300 | 94% |\n| Read package with tree | 5,000 | 1,000 | 80% |\n\n### Key Optimizations\n\n1. **Default Limits**: Returns only 50 packages by default instead of all\n2. **Lazy File Trees**: Shows only main files unless full tree is requested\n3. **Relative Paths**: Uses relative paths to save ~30% on path strings\n4. **Smart Filtering**: Multiple ways to get exactly what you need\n5. **Summary Mode**: Get counts without package details\n\n## How It Works\n\n1. **Environment Detection**: Automatically detects Python (`.venv`/`venv`) or Node.js (`package.json`) projects\n2. **Package Discovery**: \n   - Python: Scans `site-packages` and reads `.dist-info` metadata\n   - Node.js: Scans `node_modules` including scoped packages\n3. **Smart Caching**: SQLite database (`.pkg-local-cache/cache.db`) for high-performance lookups\n4. **Source Reading**: Provides file trees and actual source code to LLMs\n\n## Development\n\n### Prerequisites\n\n- Node.js 20+ (LTS recommended)\n- npm 10+ or pnpm\n- Python 3.9+ with virtual environment (for Python support)\n- Node.js project with node_modules (for Node.js support)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/descoped/mcp-pkg-local.git\ncd mcp-pkg-local\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n\n# Development mode\nnpm run dev\n\n# Clean build artifacts and cache\nnpm run clean        # Remove everything (dist, node_modules, cache)\nnpm run clean:cache  # Remove only cache files\n```\n\n### Project Structure\n\n```\nmcp-pkg-local/\n├── src/\n│   ├── index.ts          # Entry point\n│   ├── server.ts         # MCP server setup\n│   ├── tools/            # MCP tool implementations\n│   ├── scanners/         # Language-specific scanners\n│   └── utils/            # Utilities\n├── tests/                # Test suite\n└── dist/                 # Compiled output\n```\n\n## Testing\n\nThe project includes comprehensive tests using Vitest:\n\n```bash\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Run in watch mode\nnpm run test:ui\n```\n\n## Configuration\n\n### Environment Variables\n\n- `DEBUG=mcp-pkg-local:*` - Enable debug logging\n- `NODE_ENV=production` - Production mode\n\n### Cache Management\n\nThe cache system uses SQLite for optimal performance:\n- Location: `.pkg-local-cache/cache.db`\n- Mode: WAL (Write-Ahead Logging) for concurrent access\n- TTL: 1-hour default validity\n- Refresh: Use `--forceRefresh` to force rescan\n\n## Supported Environments\n\n### Python\n- ✅ Virtual environments (venv, .venv)\n- ✅ Package managers: pip, poetry, uv, pipenv (basic detection)\n- ✅ Standard pip packages\n- ✅ Editable installations (-e)\n- ✅ Namespace packages\n- ⚠️ Limited: No dependency categorization yet\n- 🚧 Conda environments (planned)\n\n### Node.js/JavaScript\n- ✅ node_modules directory\n- ✅ Package managers: npm, pnpm, yarn, bun (full support)\n- ✅ Scoped packages (@org/package)\n- ✅ TypeScript packages\n- ✅ ESM and CommonJS modules\n- ✅ Production vs development categorization\n\n## Limitations\n\n- Python dependency categorization not yet implemented\n- Local environments only (no system packages)\n- Read-only access (cannot modify packages)\n- 10MB file size limit for source files\n- Go, Rust, Java support planned for future versions\n\n## Security\n\n- Never reads files outside virtual environment or node_modules\n- Path sanitization prevents directory traversal\n- No code execution, only reading\n- Binary files are blocked\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for new features\n4. Ensure all tests pass\n5. Submit a pull request\n\n## Roadmap\n\n### v0.1.0 (Released)\n- [x] Python virtual environment support\n- [x] Basic package scanning and reading\n- [x] MCP server implementation\n- [x] Caching system\n\n### v0.1.1 (Current)\n- [x] Performance optimizations (90% token reduction)\n- [x] Advanced filtering (regex, category, groups)\n- [x] Lazy file tree loading\n- [x] Summary mode for minimal tokens\n- [x] Node.js/JavaScript support\n- [x] Multi-package manager support\n\n### Future Versions\n- [ ] Python dependency categorization (critical)\n- [ ] Smart package prioritization\n- [ ] Conda environment support\n- [ ] Package alias resolution\n- [ ] Dependency tree visualization\n\n- [ ] Go modules support\n- [ ] Rust/Cargo support\n- [ ] Auto-trigger on import detection\n- [ ] Package documentation extraction\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Acknowledgments\n\nBuilt with:\n- [Model Context Protocol SDK](https://github.com/anthropics/mcp)\n- [TypeScript](https://www.typescriptlang.org)\n- [Vitest](https://vitest.dev)\n\n## Support\n\n- [GitHub Issues](https://github.com/descoped/mcp-pkg-local/issues)\n- [Documentation](https://github.com/descoped/mcp-pkg-local/wiki)\n\n---\n\nMade with ❤️ for better LLM code generation\n","readmeFilename":"README.md"}