Releases

🚀 Major Performance Improvements

High-Performance SQLite Cache

• 40x faster validity checks (0.03ms vs 1.2ms)
• WAL mode for optimized concurrent access
• Prepared statements for efficient queries
• MessagePack serialization for binary data storage
• Response times: ~150ms scan, ~10ms read, ~5ms cache hits

Token Efficiency Optimizations

• 90% token reduction for scan-packages (20K → 2K tokens)
• 99% reduction with summary mode (20K → 200 tokens)
• 94% reduction with lazy loading (5K → 300 tokens)
• Smart limits: Default 50 packages for optimal LLM performance

✨ New Features

Advanced Filtering System

• 📊 Summary Mode: Ultra-efficient package counts only
• 🔍 Regex Filtering: Pattern-based package selection
• 📦 Category Filtering: Production vs development dependencies
• 🏷️ Group Filtering: Pre-defined groups (testing, linting, building, etc.)
• 🚫 Type Exclusion: Optionally exclude @types packages

Enhanced Package Intelligence

• 📈 Relevance Scoring: Prioritizes direct dependencies over transitive
• 🎯 Smart Prioritization: Project dependencies ranked higher
• 🌲 Lazy Loading: File trees loaded on-demand for faster navigation
• 🔄 Package Scoring: Popular packages get higher relevance scores

Developer Experience

• 🛠️ TypeScript 5.9+: Strict mode with full type safety
• 📦 ES Modules: Modern import maps (#utils, #tools, etc.)
• 🧪 Comprehensive Testing: 59 tests with 100% pass rate
• 🔧 Better Error Handling: Actionable error messages with suggestions

🏗️ Architecture Improvements

Simplified Caching

• Removed 350+ lines of dead JSON fallback code
• SQLite-only implementation (no unnecessary fallbacks)
• 87% code reduction in cache.ts (407 → 53 lines)
• Synchronous operations for better performance

Test Infrastructure

• Sequential test execution to prevent SQLite database locking
• Directory-based cache naming for proper test isolation
• 100% reliable test suite (54/54 tests pass consistently)
• 60-second timeout for performance-heavy operations

Code Quality

• 0 ESLint errors/warnings
• 0 TypeScript errors
• Safer null handling with nullish coalescing (??)
• Proper type definitions eliminating any types

📊 Statistics

Metric	Value
Files changed	53
Insertions	+8,140
Deletions	-2,464
Net change	+5,676 lines
Test coverage	59 tests (100% pass rate)
Dependencies	420 packages (0 vulnerabilities)
Build time	~2s (clean environment)

🐛 Bug Fixes

• Fixed SQLite database locking in concurrent test execution
• Resolved test robustness with better package detection
• Fixed TypeScript path mapping for #utils/sqlite-cache
• Improved cache sharing between scan and read operations
• Enhanced error handling and validation across all tools

🔧 Technical Changes

Cache System

• UnifiedCache now SQLite-only (removed PartitionedCache, IndexCache)
• Cache stored in .pkg-local-cache/cache.db (or test-specific variants)
• Automatic WAL mode for concurrent access
• Directory-based naming for test isolation
• 1-hour TTL with smart invalidation

Test Infrastructure

• vitest.config.ts: Sequential execution with pool: 'forks', singleFork: true
• Test timeout: Increased to 60s for performance benchmarks
• Cache isolation: Directory-based DB naming prevents conflicts
• 100% reliability: No more SQLite locking errors

API Consistency

• All cache methods now synchronous
• Improved type safety across all modules
• Better error messages with actionable suggestions
• Consistent logging and debugging output

🏃♂️ Performance Benchmarks

Operation	v0.1.0	v0.1.1	Improvement
Cache validity check	1.2ms	0.03ms	40x faster
Full scan tokens	20,000	2,000	90% reduction
Summary mode tokens	N/A	200	99% reduction
Lazy loading tokens	5,000	300	94% reduction
Cache hit response	50ms	5ms	10x faster
Test suite reliability	85%	100%	Consistent

---

Full Changelog: v0.1.0...v0.1.1

🎉 Initial Release

mcp-pkg-local is an 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.

✨ Features

🐍 Python Support

• Full virtual environment scanning (.venv, venv)
• Support for multiple package managers (pip, poetry, uv, pipenv, conda)
• Reads .dist-info metadata for accurate version information
• Handles editable installations and namespace packages
• Tested with 85+ packages in production environments

📦 Node.js/JavaScript Support

• Complete node_modules scanning
• Support for npm, pnpm, yarn, and bun package managers
• Handles scoped packages (@org/package)
• TypeScript package support
• ESM and CommonJS module compatibility

🛠️ MCP Tools

• scan-packages: Automatically indexes all installed packages with versions
• read-package: Navigate and read source files from any installed package
• Smart caching with 1-hour TTL for optimal performance
• Auto-detection of project type (Python or Node.js)

🏗️ Architecture

• Extensible scanner architecture with TypeScript interfaces
• Clean separation of concerns (tools, scanners, utilities)
• Full TypeScript with strict mode and Zod validation
• Modern ES modules with Node.js subpath imports

🚀 Performance

• Sub-second package scanning (~300ms for 85 packages)
• Intelligent index caching (.pkg-local-index.json)
• File size limits (10MB) with binary file protection
• Path sanitization preventing directory traversal

📋 Developer Experience

• Zero configuration for standard projects
• Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code
• Comprehensive error messages with helpful suggestions
• Debug logging support via DEBUG=mcp-pkg-local:*

🔐 Security

• Never reads files outside package directories
• Path sanitization prevents directory traversal
• No code execution, only reading
• Binary files are blocked
• Respects filesystem permissions

📊 Project Statistics

• Languages: TypeScript (100%)
• Test Coverage: 19 tests passing
• Dependencies: Minimal (only @modelcontextprotocol/sdk and zod)
• Node.js: Requires 20.x or higher
• Package Size: < 100KB (excluding dependencies)

📦 Package Details

• Name: @descoped/mcp-pkg-local
• Version: 0.1.0
• License: MIT
• Registry: https://www.npmjs.com/package/@descoped/mcp-pkg-local
• Repository: https://github.com/descoped/mcp-pkg-local