smart-coding-mcp 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,287 @@
+# Project Structure
+
+This document outlines the modular architecture of Smart Coding MCP.
+
+## Directory Structure
+
+```
+smart-coding-mcp/
+├── index.js                    # Main entry point, MCP server setup
+├── package.json                # Package configuration
+├── config.json                 # User configuration
+├── LICENSE                     # MIT License
+├── README.md                   # Project documentation
+├── EXAMPLES.md                 # Usage examples
+├── .gitignore                  # Git ignore rules
+│
+├── lib/                        # Core libraries
+│   ├── config.js              # Configuration loader
+│   ├── cache.js               # Embeddings cache management
+│   └── utils.js               # Shared utilities (chunking, similarity)
+│
+├── features/                   # Pluggable features
+│   ├── hybrid-search.js       # Semantic search feature
+│   ├── index-codebase.js      # Code indexing feature
+│   └── clear-cache.js         # Cache management feature
+│
+└── scripts/                    # Utility scripts
+    └── clear-cache.js         # Cache management utility
+```
+
+## Module Responsibilities
+
+### index.js
+
+- MCP server initialization
+- Feature registry and orchestration
+- Tool request routing
+- Global state management (embedder, cache)
+
+### lib/config.js
+
+- Loads and validates configuration from config.json
+- Provides default configuration values
+- Resolves file paths
+
+### lib/cache.js
+
+- **EmbeddingsCache** class
+- Manages persistence of embedding vectors
+- File hash tracking for change detection
+- Load/save operations for disk cache
+
+### lib/utils.js
+
+- **cosineSimilarity()** - Vector similarity calculation
+- **hashContent()** - MD5 hashing for change detection
+- **smartChunk()** - Language-aware code chunking
+
+### features/hybrid-search.js
+
+- **HybridSearch** class
+- Combines semantic and exact matching
+- Weighted scoring algorithm
+- Result formatting with relevance scores
+- MCP tool: `semantic_search`
+
+### features/index-codebase.js
+
+- **CodebaseIndexer** class
+- File discovery via glob patterns
+- Incremental indexing
+- File watcher for real-time updates
+- MCP tool: `index_codebase`
+
+## Adding New Features
+
+To extend with a new feature:
+
+### 1. Create Feature Module
+
+Create `features/my-feature.js`:
+
+```javascript
+export class MyFeature {
+  constructor(embedder, cache, config) {
+    this.embedder = embedder;
+    this.cache = cache;
+    this.config = config;
+  }
+
+  async execute(params) {
+    // Implementation
+    return {
+      /* results */
+    };
+  }
+}
+
+export function getToolDefinition(config) {
+  return {
+    name: "my_tool",
+    description: "What this tool does",
+    inputSchema: {
+      type: "object",
+      properties: {
+        param1: { type: "string", description: "..." },
+      },
+      required: ["param1"],
+    },
+  };
+}
+
+export async function handleToolCall(request, instance) {
+  const params = request.params.arguments;
+  const result = await instance.execute(params);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}
+```
+
+### 2. Register in index.js
+
+```javascript
+import * as MyFeature from "./features/my-feature.js";
+
+// In initialize():
+const myFeature = new MyFeature.MyFeature(embedder, cache, config);
+
+// Add to features array:
+const features = [
+  // ... existing features
+  {
+    module: MyFeature,
+    instance: myFeature,
+    handler: MyFeature.handleToolCall,
+  },
+];
+```
+
+### 3. Done!
+
+The feature will automatically:
+
+- Be listed in MCP tool discovery
+- Handle incoming tool requests
+- Have access to embeddings and cache
+
+## Configuration Flow
+
+1. User creates/edits `config.json`
+2. `lib/config.js` loads configuration on startup
+3. Configuration merged with defaults
+4. Passed to all features via constructor
+
+## Data Flow
+
+### Indexing Flow
+
+```
+User code files
+    ↓
+glob pattern matching
+    ↓
+smartChunk() - split into chunks
+    ↓
+embedder - generate vectors
+    ↓
+EmbeddingsCache - store in memory + disk
+```
+
+### Search Flow
+
+```
+User query
+    ↓
+embedder - query to vector
+    ↓
+cosineSimilarity() - score all chunks
+    ↓
+exact match boost - adjust scores
+    ↓
+sort and filter - top N results
+    ↓
+format output - markdown with syntax highlighting
+```
+
+## Performance Considerations
+
+### Caching Strategy
+
+- **First Run**: Download model (~90MB), index all files, save cache
+- **Subsequent Runs**: Load cache from disk, only index changed files
+- **File Changes**: Incremental updates via file watcher
+
+### Memory Usage
+
+Approximate memory usage:
+
+- Base (Node.js + libraries): ~50MB
+- Embedding model: ~100MB
+- Vector store: ~10KB per code chunk
+- Example: 1000 files × 20 chunks/file = ~200MB
+
+### Optimization Tips
+
+- Reduce `chunkSize` for large codebases
+- Disable `watchFiles` if not needed
+- Use `excludePatterns` aggressively
+- Limit `fileExtensions` to relevant types
+
+## Future Feature Ideas
+
+Potential features to add following this architecture:
+
+1. **Code Complexity Analysis**
+
+   - Cyclomatic complexity scoring
+   - Technical debt detection
+
+2. **Pattern Detection**
+
+   - Anti-pattern identification
+   - Best practice recommendations
+
+3. **Documentation Generation**
+
+   - Auto-generate function docs
+   - README generation from code
+
+4. **Refactoring Suggestions**
+
+   - Code smell detection
+   - Automated fix suggestions
+
+5. **Test Coverage Analysis**
+
+   - Identify untested code paths
+   - Generate test templates
+
+6. **Dependency Analysis**
+   - Import/export graph
+   - Dead code detection
+
+Each feature would follow the same pattern:
+
+- Class in `features/` directory
+- Access to embedder, cache, config
+- MCP tool definition and handler
+- Registration in feature array
+
+## Testing Strategy
+
+Recommended testing approach:
+
+1. **Unit Tests**: lib/ modules
+
+   - Test utilities in isolation
+   - Mock dependencies
+
+2. **Integration Tests**: features/
+
+   - Test with sample codebases
+   - Verify MCP tool contracts
+
+3. **E2E Tests**: Full workflow
+   - Index → Search → Results
+   - File watching behavior
+   - Cache persistence
+
+## Error Handling
+
+Each module follows defensive error handling:
+
+- Config errors → use defaults
+- File read errors → log and skip
+- Embedding errors → retry or skip chunk
+- Cache errors → log but continue
+- Unknown tools → return helpful error message
+
+All errors logged to stderr for MCP protocol compatibility.

package/CONTRIBUTING.md

@@ -0,0 +1,308 @@
+# Contributing to Smart Coding MCP
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn
+- Git
+
+### Setup Development Environment
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/omar-haris/smart-coding-mcp.git
+cd smart-coding-mcp
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+```
+
+## Project Structure
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed information about the modular architecture.
+
+Key directories:
+
+- `lib/` - Core libraries and utilities
+- `features/` - Pluggable feature modules
+- `scripts/` - Utility scripts
+
+## Development Guidelines
+
+### Code Style
+
+- Use ES6+ JavaScript features
+- Follow existing code patterns
+- Use meaningful variable and function names
+- Add comments for complex logic
+- No emojis in code or documentation
+
+### File Organization
+
+```javascript
+// Standard file structure for features:
+
+// 1. Imports
+import { dependency } from "package";
+
+// 2. Class definition
+export class FeatureName {
+  constructor(embedder, cache, config) {
+    // ...
+  }
+
+  async method() {
+    // ...
+  }
+}
+
+// 3. MCP tool definition
+export function getToolDefinition(config) {
+  return {
+    /* ... */
+  };
+}
+
+// 4. Tool handler
+export async function handleToolCall(request, instance) {
+  // ...
+}
+```
+
+### Error Handling
+
+```javascript
+// Always handle errors gracefully
+try {
+  // operation
+} catch (error) {
+  console.error("[Module] Error description:", error.message);
+  // Continue execution or return default value
+}
+```
+
+### Logging
+
+Use `console.error()` for all logs (MCP protocol requirement):
+
+```javascript
+console.error("[FeatureName] Informational message");
+console.error("[FeatureName] Warning:", details);
+console.error("[FeatureName] Error:", error.message);
+```
+
+## Adding New Features
+
+### Step-by-Step Guide
+
+1. **Create Feature File**
+
+Create `features/your-feature.js`:
+
+```javascript
+export class YourFeature {
+  constructor(embedder, cache, config) {
+    this.embedder = embedder;
+    this.cache = cache;
+    this.config = config;
+  }
+
+  async execute(params) {
+    // Implementation
+    return { result: "data" };
+  }
+}
+
+export function getToolDefinition(config) {
+  return {
+    name: "your_tool",
+    description: "Clear description of what the tool does",
+    inputSchema: {
+      type: "object",
+      properties: {
+        param: {
+          type: "string",
+          description: "Parameter description",
+        },
+      },
+      required: ["param"],
+    },
+  };
+}
+
+export async function handleToolCall(request, instance) {
+  const params = request.params.arguments;
+  const result = await instance.execute(params);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}
+```
+
+2. **Register Feature**
+
+Update `index.js`:
+
+```javascript
+import * as YourFeature from "./features/your-feature.js";
+
+// In initialize():
+const yourFeature = new YourFeature.YourFeature(embedder, cache, config);
+
+// Add to features array:
+features.push({
+  module: YourFeature,
+  instance: yourFeature,
+  handler: YourFeature.handleToolCall,
+});
+```
+
+3. **Test Your Feature**
+
+- Test with sample codebase
+- Verify MCP tool contract
+- Check error handling
+- Validate output format
+
+4. **Document Your Feature**
+
+- Add to README.md features section
+- Create examples in EXAMPLES.md
+- Update ARCHITECTURE.md if needed
+
+## Pull Request Process
+
+1. **Fork the repository**
+
+2. **Create a feature branch**
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+3. **Make your changes**
+
+- Follow code style guidelines
+- Add appropriate comments
+- Test thoroughly
+
+4. **Commit your changes**
+
+```bash
+git add .
+git commit -m "Add feature: description"
+```
+
+Follow commit message conventions:
+
+- `Add feature: description` - New features
+- `Fix: description` - Bug fixes
+- `Update: description` - Updates to existing code
+- `Docs: description` - Documentation changes
+
+5. **Push to your fork**
+
+```bash
+git push origin feature/your-feature-name
+```
+
+6. **Create Pull Request**
+
+- Provide clear description of changes
+- Reference any related issues
+- Include examples of usage
+- Explain testing performed
+
+## Testing
+
+### Manual Testing
+
+```bash
+# Test with a sample project
+cd /path/to/test/project
+node /path/to/smart-coding-mcp/index.js
+
+# In another terminal, send MCP requests
+```
+
+### Testing MCP Tools
+
+Create a test script:
+
+```javascript
+// test-tool.js
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+// ... setup and test your tool
+```
+
+## Configuration Changes
+
+If adding new configuration options:
+
+1. Update `lib/config.js` with new default values
+2. Document in README.md
+3. Add examples to EXAMPLES.md
+4. Consider backward compatibility
+
+## Documentation
+
+All documentation should:
+
+- Be clear and concise
+- Include code examples
+- Avoid emojis
+- Use proper markdown formatting
+- Be kept up-to-date with code changes
+
+## Code Review Checklist
+
+Before submitting a PR, verify:
+
+- [ ] Code follows project style guidelines
+- [ ] No console.log (use console.error for MCP)
+- [ ] Error handling is implemented
+- [ ] Configuration changes are documented
+- [ ] README.md is updated if needed
+- [ ] No breaking changes without discussion
+- [ ] Comments explain complex logic
+- [ ] No emojis in code or documentation
+
+## Feature Ideas
+
+Looking for ideas? Consider implementing:
+
+- Code complexity analysis
+- Pattern detection and anti-pattern identification
+- Documentation generation
+- Refactoring suggestions
+- Test coverage analysis
+- Dependency graph visualization
+- Performance profiling integration
+- Multi-language translation support
+
+## Questions and Support
+
+- **Issues**: Use GitHub Issues for bugs and feature requests
+- **Discussions**: Use GitHub Discussions for questions
+- **Email**: Contact Omar Haris via LinkedIn
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to Smart Coding MCP!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Omar Haris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.