{"_id":"@crisnc100/smart-context-mcp","_rev":"3-b6503873aa63c3eed6840930be775472","name":"@crisnc100/smart-context-mcp","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@crisnc100/smart-context-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","context-pruning","llm","ai","code-analysis","semantic-search","machine-learning"],"author":{"name":"Cristian Ortega"},"license":"MIT","_id":"@crisnc100/smart-context-mcp@1.0.0","maintainers":[{"name":"crisnc100","email":"crisnc100@gmail.com"}],"homepage":"https://github.com/crisnc100/smart-context-mcp#readme","bugs":{"url":"https://github.com/crisnc100/smart-context-mcp/issues"},"bin":{"smart-context":"bin/smart-context.js"},"dist":{"shasum":"3c2577621651b9fe26f2f02f566f93514c8caa12","tarball":"https://registry.npmjs.org/@crisnc100/smart-context-mcp/-/smart-context-mcp-1.0.0.tgz","fileCount":21,"integrity":"sha512-8VPV4A1djEZMUtgUCdE+U6O1Ht20LtLkRtsjaaWkMg3MVMbJtT/Z6FsWI28agw1VysuIwq1ErZ/f+AKWF4hZ0Q==","signatures":[{"sig":"MEUCIQCyPnx4z/4NYziM0g4UZY7uKQRavjfcBy0dLatt5xWMEgIgE9BLUZzegOYm/FwspYCFftWm8OQXt0s1wBuAG3tDZds=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":132206},"main":"src/index.js","type":"module","engines":{"node":">=16.0.0"},"gitHead":"1efbd056f1b49e72f5b1781116d6d3bc4234a844","scripts":{"dev":"nodemon src/index.js","test":"node test/test-final-validation.js","start":"node src/index.js","test:all":"npm run test:scanner && npm run test:performance && npm run test:error && npm run test","test:error":"node test/test-error-handling.js","test:scanner":"node test/test-scanner.js","version:major":"node scripts/version.js major","version:minor":"node scripts/version.js minor","version:patch":"node scripts/version.js patch","test:performance":"node test/test-performance.js"},"_npmUser":{"name":"crisnc100","email":"crisnc100@gmail.com"},"repository":{"url":"git+https://github.com/crisnc100/smart-context-mcp.git","type":"git"},"_npmVersion":"10.9.2","description":"Intelligent MCP server for optimal file context selection in LLM coding tasks","directories":{},"_nodeVersion":"22.14.0","dependencies":{"glob":"^10.3.10","uuid":"^9.0.1","ignore":"^5.3.0","rimraf":"^5.0.5","sql.js":"^1.8.0","fs-extra":"^11.2.0","stopword":"^2.0.8","compromise":"^14.13.0","simple-git":"^3.21.0","gpt-tokenizer":"^2.1.2","@modelcontextprotocol/sdk":"^0.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"nodemon":"^3.0.2"},"_npmOperationalInternal":{"tmp":"tmp/smart-context-mcp_1.0.0_1753474440805_0.7936082276181786","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@crisnc100/smart-context-mcp","version":"1.1.0","keywords":["mcp","model-context-protocol","context-pruning","llm","ai","code-analysis","semantic-search","machine-learning"],"author":{"name":"Cristian Ortega"},"license":"MIT","_id":"@crisnc100/smart-context-mcp@1.1.0","maintainers":[{"name":"crisnc100","email":"crisnc100@gmail.com"}],"homepage":"https://github.com/crisnc100/smart-context-mcp#readme","bugs":{"url":"https://github.com/crisnc100/smart-context-mcp/issues"},"bin":{"smart-context":"bin/smart-context.js"},"dist":{"shasum":"20259e8532c9c652b14da2b66f75996654ac3ef7","tarball":"https://registry.npmjs.org/@crisnc100/smart-context-mcp/-/smart-context-mcp-1.1.0.tgz","fileCount":28,"integrity":"sha512-P6yUTqWm9EVFbUYHSxy6T1a/qGH/GKA/nXO3fkbiFIB/mhOdussX2mgmCs3aQ1iQRiRTZ6IRSbvseOMBwyW1Zg==","signatures":[{"sig":"MEQCIH8kl63tCyL39PlmkP9ZprJD0/YuwvQoFXSh4/l4ncCZAiAzbMFNt51cz0dMjTkQwu+ekwb8ULnYyAwgjixrAV0UKw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":216075},"main":"src/index.js","type":"module","engines":{"node":">=16.0.0"},"gitHead":"51370e13ff276515bd0fb92d228c3aa8b9083773","scripts":{"dev":"nodemon src/index.js","test":"node test/test-final-validation.js","start":"node src/index.js","test:all":"npm run test:scanner && npm run test:performance && npm run test:error && npm run test","test:error":"node test/test-error-handling.js","test:scanner":"node test/test-scanner.js","version:major":"node scripts/version.js major","version:minor":"node scripts/version.js minor","version:patch":"node scripts/version.js patch","test:performance":"node test/test-performance.js"},"_npmUser":{"name":"crisnc100","email":"crisnc100@gmail.com"},"repository":{"url":"git+https://github.com/crisnc100/smart-context-mcp.git","type":"git"},"_npmVersion":"10.9.2","description":"Intelligent MCP server for optimal file context selection in LLM coding tasks","directories":{},"_nodeVersion":"22.14.0","dependencies":{"glob":"^10.3.10","uuid":"^9.0.1","ignore":"^5.3.0","rimraf":"^5.0.5","sql.js":"^1.8.0","fs-extra":"^11.2.0","stopword":"^2.0.8","compromise":"^14.13.0","simple-git":"^3.21.0","gpt-tokenizer":"^2.1.2","@modelcontextprotocol/sdk":"^0.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"nodemon":"^3.0.2"},"_npmOperationalInternal":{"tmp":"tmp/smart-context-mcp_1.1.0_1754259905378_0.7581090119695728","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@crisnc100/smart-context-mcp","version":"2.0.0","description":"AI Context Engineer: Intelligent MCP server that generates complete context packages for LLM coding tasks, with grep assistance and semantic understanding","main":"src/index.js","type":"module","bin":{"smart-context":"bin/smart-context.js"},"scripts":{"start":"node src/index.js","dev":"nodemon src/index.js","test":"node test/test-final-validation.js","test:all":"npm run test:scanner && npm run test:performance && npm run test:error && npm run test","test:scanner":"node test/test-scanner.js","test:performance":"node test/test-performance.js","test:error":"node test/test-error-handling.js","version:patch":"node scripts/version.js patch","version:minor":"node scripts/version.js minor","version:major":"node scripts/version.js major"},"keywords":["mcp","model-context-protocol","context-engineering","ai-context-package","grep-assistant","llm","ai","code-analysis","semantic-search","machine-learning"],"engines":{"node":">=16.0.0"},"author":{"name":"Cristian Ortega"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/crisnc100/smart-context-mcp.git"},"bugs":{"url":"https://github.com/crisnc100/smart-context-mcp/issues"},"homepage":"https://github.com/crisnc100/smart-context-mcp#readme","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^0.5.0","sql.js":"^1.8.0","gpt-tokenizer":"^2.1.2","fs-extra":"^11.2.0","glob":"^10.3.10","ignore":"^5.3.0","simple-git":"^3.21.0","compromise":"^14.13.0","stopword":"^2.0.8","uuid":"^9.0.1","rimraf":"^5.0.5"},"devDependencies":{"nodemon":"^3.0.2"},"_id":"@crisnc100/smart-context-mcp@2.0.0","gitHead":"a6892ea59b63c8f287565eae699f60a6a4d97b25","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-x4eM73WZRUZ4U1zSNXZdcCDOs4T/6yLV5IOfiepPaNrcqhnCF1aG5kNKtFcMKrNvGhNLPY1l9jg9Xt6vHMX7wQ==","shasum":"4c63a41a21765acf3d2e59d7659010d20096a65a","tarball":"https://registry.npmjs.org/@crisnc100/smart-context-mcp/-/smart-context-mcp-2.0.0.tgz","fileCount":29,"unpackedSize":266483,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIClqlbaKTg4hQgY+QFzLqArVDVea88CxRZklrUCkM3b/AiEAvx591xYA6LhtzI3eY79V2wRP77sywp/KbbOH6MsJr3A="}]},"_npmUser":{"name":"crisnc100","email":"crisnc100@gmail.com"},"directories":{},"maintainers":[{"name":"crisnc100","email":"crisnc100@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smart-context-mcp_2.0.0_1756932966479_0.11091451150927156"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-25T20:14:00.693Z","modified":"2025-09-03T20:56:06.938Z","1.0.0":"2025-07-25T20:14:01.058Z","1.1.0":"2025-08-03T22:25:05.591Z","2.0.0":"2025-09-03T20:56:06.719Z"},"bugs":{"url":"https://github.com/crisnc100/smart-context-mcp/issues"},"author":{"name":"Cristian Ortega"},"license":"MIT","homepage":"https://github.com/crisnc100/smart-context-mcp#readme","keywords":["mcp","model-context-protocol","context-engineering","ai-context-package","grep-assistant","llm","ai","code-analysis","semantic-search","machine-learning"],"repository":{"type":"git","url":"git+https://github.com/crisnc100/smart-context-mcp.git"},"description":"AI Context Engineer: Intelligent MCP server that generates complete context packages for LLM coding tasks, with grep assistance and semantic understanding","maintainers":[{"name":"crisnc100","email":"crisnc100@gmail.com"}],"readme":"# Smart Context MCP Server 🎯 - AI Context Engineer\n\n[![Version](https://img.shields.io/npm/v/@crisnc100/smart-context-mcp)](https://www.npmjs.com/package/@crisnc100/smart-context-mcp)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](package.json)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)\n\n**🚀 Version 2.0.0 - Major Update!** Smart Context has evolved from a file selector to a comprehensive **AI Context Engineer** that generates complete context packages for LLMs. Transform vague queries into structured, actionable context with code, relationships, and insights.\n\n## 🎯 What's New in v2.0.0\n\n### From File Selector to AI Context Engineer\nSmart Context now acts as your personal AI Context Engineer, solving a critical problem: **users often don't provide enough context for AI tools to work effectively**. Instead of just suggesting files, it now:\n\n- **Extracts actual code** from functions and relevant sections\n- **Maps relationships** between files through imports/exports\n- **Recognizes error patterns** and suggests fixes\n- **Generates structured packages** optimized for AI consumption\n- **Works alongside grep** to enhance, not replace, traditional search\n\n### New Tool: `generate_context_package`\nThe flagship feature that transforms any query into a complete context package:\n```javascript\n// Before v2.0.0: Just file paths\n[\"src/cart.js\", \"src/checkout.js\"]\n\n// After v2.0.0: Complete context with code\n{\n  \"context\": {\n    \"coreImplementation\": {\n      \"code\": \"const getTotalPrice = () => { ... }\",\n      \"function\": \"getTotalPrice\",\n      \"lines\": \"48-56\"\n    }\n  },\n  \"relationships\": {\n    \"dependencies\": [...],\n    \"provides\": [...]\n  },\n  \"suggestedFix\": {\n    \"pattern\": \"NaN in calculation\",\n    \"suggestion\": \"Check if item.price is undefined\"\n  }\n}\n```\n\n## 🚀 Quick Start\n\n**New to Smart Context?** Follow our [5-minute setup guide](./QUICK_START.md) to get started right away!\n\n**Already familiar with MCP?** Jump to [Installation](#installation) below.\n\n## ✨ Key Features\n\n- **🧠 Semantic Understanding**: Uses NLP to understand what you're trying to accomplish, not just keywords\n- **🎯 Task-Specific Modes**: Automatically adapts strategy for debugging, feature development, and refactoring\n- **📊 Full Transparency**: See confidence scores and reasoning behind every file recommendation\n- **📈 Progressive Loading**: Start with immediate context, expand when you need more\n- **💬 Conversation Awareness**: Remembers what files you've already seen to avoid repetition\n- **🔗 Git Integration**: Learns from your commit history to predict related files\n- **🎓 Learning from Usage**: Gets smarter over time by tracking which files actually helped you\n- **🛡️ Robust Error Handling**: \n  - Works with any project (Git or non-Git)\n  - Gracefully skips large or problematic files\n  - Handles Unicode and special characters\n  - Never crashes on file permission issues\n- **⚡ Performance Optimized**:\n  - Fast parallel file processing (~85 files/second)\n  - Smart caching for instant responses\n  - Configurable limits to control resource usage\n  - Memory-efficient for large codebases\n\n## 📦 Installation\n\nChoose the method that works best for you:\n\n### 🌟 Method 1: NPM Package (Recommended)\n**Easiest for most users**\n```bash\nnpm install -g @crisnc100/smart-context-mcp\n```\n\n### 🔧 Method 2: Direct from GitHub\n**For developers who want the latest code**\n```bash\ngit clone https://github.com/crisnc100/smart-context-mcp.git\ncd smart-context-mcp\nnpm install\n```\n\n### 🐳 Method 3: Docker (Experimental)\n**For containerized deployments**\n```bash\ndocker pull smartcontext/mcp-server:latest\ndocker run -it -v $(pwd):/workspace:ro smartcontext/mcp-server\n```\n\n📋 **Need detailed setup instructions?** See our comprehensive [Installation Guide](./INSTALLATION.md) for platform-specific instructions.\n\n## Usage\n\n### For Claude Code CLI (Project-Specific)\n\nInstall in your project:\n```bash\ncd your-project\nnpm install @crisnc100/smart-context-mcp\n```\n\nCreate `.mcp.json` in project root:\n```json\n{\n  \"mcpServers\": {\n    \"smart-context\": {\n      \"command\": \"node\",\n      \"args\": [\"./node_modules/@crisnc100/smart-context-mcp/src/index.js\"],\n      \"env\": {\n        \"PROJECT_ROOT\": \".\"\n      }\n    }\n  }\n}\n```\n\nSee [CLAUDE_CODE_SETUP.md](./CLAUDE_CODE_SETUP.md) for detailed instructions.\n\n### For Claude Desktop (Global)\n\n**IMPORTANT**: Smart Context needs to know WHERE your project files are located. You must set `PROJECT_ROOT` for each project.\n\n#### For NPM Installation:\n```json\n{\n  \"mcpServers\": {\n    \"smart-context\": {\n      \"command\": \"npx\",\n      \"args\": [\"@crisnc100/smart-context-mcp\"],\n      \"env\": {\n        \"PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n#### For Local Installation:\n```json\n{\n  \"mcpServers\": {\n    \"smart-context\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/smart_context_mcp/src/index.js\"],\n      \"env\": {\n        \"PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n### For Codex CLI (OpenAI)\n\n**IMPORTANT**: Codex CLI uses `mcp_servers` (underscore) rather than `mcpServers` (camelCase).\n\n#### For NPM Installation (TOML format):\n```toml\n[mcp_servers.smart-context]\ncommand = \"npx\"\nargs = [\"-y\", \"@crisnc100/smart-context-mcp\"]\nenv = { \"PROJECT_ROOT\" = \"/path/to/your/project\" }\n```\n\n#### For Local Installation (TOML format):\n```toml\n[mcp_servers.smart-context]\ncommand = \"node\"\nargs = [\"/path/to/smart_context_mcp/src/index.js\"]\nenv = { \"PROJECT_ROOT\" = \"/path/to/your/project\" }\n```\n\n**First Time Setup?** Run the setup wizard tool in Claude:\n```\nUse the setup_wizard tool to check my Smart Context configuration\n```\n\n## 🛠️ Available Tools\n\n### 🎯 `setup_wizard` - **START HERE!**\nConfigure Smart Context for your project. This is your first step!\n\n**What it does:** Checks your configuration and helps set up Smart Context properly.\n\n**Key parameters:**\n- `action`: Choose 'check' to verify setup, 'configure' to set up a new project\n- `projectPath`: Where your code lives\n- `projectName`: A friendly name for your project\n\n### 🚀 `generate_context_package` - **AI Context Engineer** (New in v2.0.0!)\nGenerate a complete context package with code, relationships, and insights for any task.\n\n**What it does:** Acts as your AI Context Engineer - analyzes your query, extracts actual code, maps dependencies, and provides structured context that helps AI tools understand your codebase better.\n\n**Key parameters:**\n- `query` (required): Natural language description of your task\n- `currentFile`: The file you're working on (optional)\n- `tokenBudget`: Maximum tokens to use (default: 6000)\n\n**Returns:** A structured context package containing:\n- **Understanding**: What the AI understood from your query\n- **Context**: Actual code extracted from relevant sections\n- **Relationships**: Import/export dependencies and connections\n- **Suggested Fix**: Pattern-based fix suggestions for common issues\n- **Summary**: Task mode, confidence, and reasoning\n\n**Example - Debugging:**\n```javascript\n// Query: \"getTotalPrice returns NaN when cart has items\"\n{\n  \"understanding\": {\n    \"problemDescription\": \"getTotalPrice function returns NaN\",\n    \"concepts\": [\"pricing\", \"cart\", \"calculation\"],\n    \"entities\": [\"getTotalPrice\", \"cart\", \"items\"]\n  },\n  \"context\": {\n    \"coreImplementation\": {\n      \"file\": \"src/context/CartContext.js\",\n      \"function\": \"getTotalPrice\",\n      \"lines\": \"48-56\",\n      \"code\": \"const getTotalPrice = () => {\\n  return cartItems.reduce((total, item) => {\\n    return total + (item.price * item.quantity);\\n  }, 0).toFixed(2);\\n};\"\n    }\n  },\n  \"suggestedFix\": {\n    \"pattern\": \"NaN in calculation\",\n    \"confidence\": 0.8,\n    \"suggestion\": \"Check if item.price or item.quantity are undefined/null\"\n  }\n}\n```\n\n**Example - Feature Development:**\n```javascript\n// Query: \"add discount code feature to shopping cart\"\n{\n  \"understanding\": {\n    \"taskType\": \"feature\",\n    \"components\": [\"discount\", \"cart\", \"validation\"],\n    \"relatedFeatures\": [\"pricing\", \"checkout\"]\n  },\n  \"relationships\": {\n    \"dependencies\": [\n      {\"file\": \"CartContext.js\", \"imports\": [\"useState\", \"useEffect\"]},\n      {\"file\": \"api/checkout.js\", \"exports\": [\"applyDiscount\", \"validateCode\"]}\n    ],\n    \"provides\": [\"CartProvider\", \"useCart\", \"getTotalPrice\"]\n  }\n}\n```\n\n### 🔍 `get_optimal_context` - **File Selection Tool**\nGet the most relevant files for any coding task with grep commands.\n\n**What it does:** Analyzes your task and returns the best files to include in context, plus grep commands to search for specific patterns.\n\n**Key parameters:**\n- `task` (required): Describe what you're trying to do (\"fix login bug\", \"add new feature\")\n- `currentFile`: The file you're currently working on\n- `targetTokens`: How many tokens you want to use (default: 6000)\n- `progressiveLevel`: 1=immediate context, 2=expanded, 3=comprehensive\n\n### `set_project_scope`\nConfigure file patterns to include/exclude for large projects.\n\n**Parameters:**\n- `name`: Name for this scope configuration\n- `includePaths`: Glob patterns to include (e.g., \"src/**\")\n- `excludePaths`: Glob patterns to exclude\n- `maxDepth`: Maximum directory depth\n- `activate`: Whether to activate immediately\n\n### `record_session_outcome`\nProvide feedback on which files were actually helpful.\n\n**Parameters:**\n- `sessionId` (required): Session ID from get_optimal_context\n- `wasSuccessful` (required): Whether the task was completed successfully\n- `filesActuallyUsed`: Array of files that were actually helpful\n\n### `search_codebase`\nSemantic search across the codebase.\n\n**Parameters:**\n- `query` (required): Natural language search query\n- `limit`: Maximum results to return (default: 10)\n\n### `get_file_relationships`\nGet files related to a specific file.\n\n**Parameters:**\n- `filePath` (required): File to find relationships for\n- `relationshipType`: 'import', 'git-co-change', or 'all'\n\n### `analyze_git_patterns`\nAnalyze git history for file relationships.\n\n**Parameters:**\n- `commitLimit`: Number of commits to analyze (default: 100)\n\n### `get_learning_insights`\nGet insights about learned patterns.\n\n**Parameters:**\n- `taskMode`: Filter by 'debug', 'feature', or 'refactor'\n\n### `apply_user_overrides`\nApply manual file selection adjustments for learning.\n\n**Parameters:**\n- `sessionId`: Session ID from get_optimal_context\n- `added`: Files manually added\n- `removed`: Files manually removed\n- `kept`: Files accepted as-is\n\n## Example Usage in Claude\n\n```\n// First time setup\nUse the setup_wizard tool with action=\"check\"\n\n// Generate complete context package (v2.0.0 - AI Context Engineer)\nUse generate_context_package with query=\"getTotalPrice returns NaN in cart\"\nUse generate_context_package to understand \"how does the authentication system work\"\nUse generate_context_package for \"add email notification when order ships\"\n\n// Get relevant files with grep commands\nUse get_optimal_context to find files related to \"fixing the user authentication flow\"\n\n// Search for specific concepts\nUse search_codebase to find files containing \"websocket connection handling\"\n\n// Configure for large projects\nUse set_project_scope to only include src/** and exclude test files\n```\n\n## How It Works\n\n### Version 2.0.0 - AI Context Engineer\nSmart Context has evolved from a file selector to a comprehensive **AI Context Engineer** that:\n\n1. **Understands Your Query**: Uses NLP to extract intent, concepts, entities, and error patterns\n2. **Extracts Real Code**: Finds and extracts actual functions and code sections, not just file paths\n3. **Maps Relationships**: Analyzes imports, exports, and dependencies between files\n4. **Suggests Fixes**: Recognizes common error patterns (NaN, null, undefined) and suggests solutions\n5. **Enforces Token Budgets**: Intelligently allocates tokens across different context sections\n6. **Learns From Usage**: Tracks which files and code sections actually helped solve problems\n\n### Core Process\n1. **Query Analysis**: Deep semantic understanding of your task\n2. **Multi-Factor Scoring**: Files scored on semantic similarity, git history, imports, and learned patterns\n3. **Code Extraction**: Pulls specific functions and relevant code sections\n4. **Relationship Mapping**: Builds dependency graph of your codebase\n5. **Context Generation**: Creates structured package optimized for AI consumption\n\n## Task Modes\n\n- **Debug Mode**: Prioritizes recently changed files, error handlers, and test files\n- **Feature Mode**: Focuses on interfaces, similar features, and type definitions  \n- **Refactor Mode**: Includes all usages, dependencies, and related tests\n\n## Configuration\n\nThe server can be configured through:\n\n1. **Configuration file** (`config/default.json`)\n2. **Local overrides** (`config/local.json`)\n3. **Environment variables**\n\n### Configuration Options\n\n```json\n{\n  \"context\": {\n    \"defaultTokenBudget\": 6000,\n    \"minRelevanceScore\": 0.3,\n    \"progressiveLevels\": {\n      \"immediate\": 0.6,\n      \"expanded\": 0.4,\n      \"comprehensive\": 0.2\n    }\n  },\n  \"fileScanning\": {\n    \"maxFileSize\": 1048576,  // 1MB in bytes\n    \"ignorePatterns\": [\"node_modules/**\", \"*.log\"]\n  },\n  \"git\": {\n    \"recentChangesHours\": 48,\n    \"defaultCommitLimit\": 100\n  }\n}\n```\n\n### Environment Variables\n\n- `SMART_CONTEXT_TOKEN_BUDGET` - Override default token budget\n- `SMART_CONTEXT_MIN_RELEVANCE` - Minimum relevance score threshold\n- `SMART_CONTEXT_MAX_FILE_SIZE` - Maximum file size to scan (in bytes)\n- `SMART_CONTEXT_GIT_COMMIT_LIMIT` - Number of commits to analyze\n\n## Performance Optimization\n\nFor large projects:\n\n1. **Use Project Scopes**: Configure include/exclude patterns with `set_project_scope`\n2. **Adjust Token Budget**: Lower `targetTokens` for faster responses\n3. **Set Relevance Threshold**: Increase `minRelevanceScore` to be more selective\n4. **Progressive Loading**: Start with `progressiveLevel: 1` for immediate context\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# All tests\nnpm run test:all\n\n# Individual test suites\nnpm run test:scanner      # File scanning tests\nnpm run test:performance  # Performance benchmarks\nnpm run test:error        # Error handling tests\nnpm test                  # Full validation suite\n```\n\n### Available Test Files\n\n- `test-final-validation.js` - Main validation suite\n- `test-scanner.js` - File scanning functionality\n- `test-performance.js` - Performance benchmarks\n- `test-error-handling.js` - Error handling tests\n- `test-cross-platform.js` - Cross-platform compatibility\n- `test-mcp-server.js` - MCP server functionality\n- `run-all-tests.js` - Test runner for all suites\n- Various scenario tests for query styles, edge cases, and real-world usage\n\n## 📊 Performance\n\nPerformance characteristics:\n- **Scanning**: ~85 files/second\n- **Response**: <200ms (warm cache)\n- **Memory**: ~30KB per file\n- **Accuracy**: 85%+ relevance\n\n## 🔍 How It Works\n\nThe Smart Context MCP Server uses a multi-factor scoring system:\n\n1. **Semantic Analysis**: NLP understanding of your task\n2. **Import Graph**: Traces code dependencies\n3. **Git History**: Analyzes co-change patterns\n4. **Learning System**: Improves from your feedback\n5. **Task Modes**: Adapts strategy for debug/feature/refactor\n\nSee [TEST_RESULTS_COMPREHENSIVE.md](./TEST_RESULTS_COMPREHENSIVE.md) for technical details.\n\n## 📚 Documentation\n\n- [Installation Guide](./INSTALLATION.md) - Platform-specific setup instructions\n- [Quick Start Guide](./QUICK_START.md) - Get running in 5 minutes\n- [Setup Visual Guide](./SETUP_VISUAL_GUIDE.md) - Step-by-step with screenshots\n- [API Documentation](./API_DOCUMENTATION.md) - Complete API reference\n- [Claude Code Setup](./CLAUDE_CODE_SETUP.md) - Setup for Claude Code CLI\n- [Docker Setup](./DOCKER_SETUP.md) - Docker deployment guide\n- [Test Results](./TEST_RESULTS_COMPREHENSIVE.md) - Comprehensive test analysis\n- [Feedback Analysis](./FEEDBACK_ANALYSIS.md) - User feedback and improvements\n- [Improvements v1.0.1](./IMPROVEMENTS_v1.0.1.md) - Latest version improvements\n- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues and solutions\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n**\"No files found\"**\n- Run `setup_wizard` with `action=\"check\"` to verify configuration\n- Ensure `PROJECT_ROOT` points to your actual project directory\n- Check that the directory contains code files (.js, .ts, .py, etc.)\n\n**\"Server doesn't appear in Claude\"**\n- Fully restart Claude Desktop (not just reload)\n- Check JSON syntax in your config file\n- Verify the command path exists\n\n**Performance issues**\n- Use `set_project_scope` to limit scanning area\n- Reduce token budget or increase relevance threshold\n\nSee [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for comprehensive solutions and [Issues](https://github.com/crisnc100/smart-context-mcp/issues) for more help.\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing`)\n5. Open a Pull Request\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- Built for the [Model Context Protocol](https://modelcontextprotocol.io)\n- Inspired by the need for smarter context in LLM-assisted coding\n- Pure JavaScript implementation for maximum compatibility\n\n---\n\n**Ready to code smarter?** Install Smart Context and let it learn what files matter for your tasks! 🚀","readmeFilename":"README.md"}