codeweaver-mcp
by nobiehl
README.md
# CodeWeaver 🕸️
> ⚠️ **Beta Release (v0.6.0)** - Static Analysis + Code Cleanup! SpotBugs & Checkstyle integration, all packages updated, codebase fully cleaned. PMD & SonarLint coming soon!
**Token-efficient MCP server for Multi-Language project analysis (Java, TypeScript, JavaScript, Markdown, Python)**
Weaving Code Intelligence for LLMs - A lightweight Model Context Protocol server that provides token-efficient access to Java, TypeScript, JavaScript, Markdown, and Python files through a multi-agent architecture with language plugins.
## ⚡ Highlights
- ✅ **Zero Native Dependencies*** - Pure Node.js/TypeScript with language-specific parsers
- ✅ **Dual Interface** - CLI tool AND MCP server from same codebase
- ✅ **Token-Efficient** - Smart file reading with token limits
- ✅ **Multi-Language Support** 🆕 - Java, TypeScript, JavaScript, Markdown, AND Python with unified plugin architecture!
- 🎯 **Complete Java Support** (Java 8-23) - Records, Sealed Classes, Module System
- 🎯 **Complete TypeScript Support** - Classes, Interfaces, Types, Enums, Generics, Decorators
- 🎯 **Complete JavaScript Support** - Modern ES6+, JSX, Arrow Functions, Async/Await
- 🎯 **Complete Markdown Support** - Headers as Sections, Links as References, Code Blocks
- 🎯 **Complete Python Support** 🆕 - Classes, Functions, Methods, Decorators, Type Hints, Async/Await
- ✅ **Class-Level Annotations/Decorators** - Spring, JPA, Jakarta EE, TypeScript decorators, Python @decorators
- ✅ **Method Parameters** - Names, types, and annotations extracted
- ✅ **Generic Type Parameters** - Full signature with bounds (Java, TypeScript)
- ✅ **Language Field** - Every symbol tagged with source language
- ✅ **Easy Extensibility** - Plugin system for adding new languages
- ✅ **Powerful Search** - Keyword, pattern, AND semantic search (AI-powered) 🆕
- ✅ **Semantic Code Search** - Find code by meaning/intent using LanceDB + Transformers 🆕
- ⚡ **ONNX Runtime Optimizations** - Multi-threading + SIMD for 3x faster embeddings! 🆕
- ⚡ **16x faster with Batch-Processing** - 10k files in ~10 min (was 8h!)
- 🎯 **Multi-Collection Support** - Separate indexes for Code AND Docs! 🆕
- 🔍 **File Watcher** - Automatic incremental updates on file changes! 🆕
- 📖 **[SEMANTIC_SEARCH.md](./docs/guides/SEMANTIC_SEARCH.md)** - Comprehensive guide with workflows and best practices
- 🎯 **[MULTI_COLLECTION_GUIDE.md](./docs/guides/MULTI_COLLECTION_GUIDE.md)** - Multi-collection usage guide (Code + Docs)
- 🔍 **[FILE_WATCHER_GUIDE.md](./docs/guides/FILE_WATCHER_GUIDE.md)** - Keep your index always up-to-date!
- 🚀 **[PERFORMANCE_OPTIMIZATION.md](./docs/architecture/PERFORMANCE_OPTIMIZATION.md)** - Future optimizations (GPU acceleration)
- ✅ **Code Quality Analysis** - Cyclomatic complexity, LOC metrics, import analysis
- ✅ **Static Analysis** 🆕 - SpotBugs (bugs), Checkstyle (style) with plugin architecture!
- 🔬 **SpotBugs** - Finds NullPointerExceptions, Resource Leaks, SQL Injections
- ✅ **Checkstyle** - Code style enforcement, naming conventions
- 🔌 **Plugin Architecture** - Easy to add PMD, SonarLint later
- ✅ **Git Integration** - Status, diff, blame, log, branches, compare
- ✅ **Test-Driven** - 291 tests passing (100%) - All features fully tested! 🆕
> **\*** Core features (Discovery, Symbols, Search, Analysis, VCS) have zero native dependencies. Semantic Search optionally requires LanceDB + ONNX Runtime (native components).
---
## 🚀 Quick Start
```bash
# Install
npm install
# Build
npm run build
# Use as CLI
npm run dev -- info
npm run dev -- symbols index
npm run dev -- search keyword "CodeWeaver"
npm run dev -- analysis project
# Use as MCP Server
npm run dev -- --mcp
```
### 📖 Documentation
**📚 [Complete Documentation Index](./docs/INDEX.md)** - Full navigation of all CodeWeaver documentation
**Quick Links:**
| Category | Documents | Description |
|----------|-----------|-------------|
| **🚀 Getting Started** | [QUICKSTART](./docs/getting-started/QUICKSTART.md) • [WORKFLOW](./docs/getting-started/DEVELOPER_WORKFLOW.md) • [PRODUCTION](./docs/getting-started/PRODUCTION_READINESS.md) | Installation, tutorials, deployment |
| **📖 Reference** | [API](./docs/reference/API.md) • [USAGE](./docs/reference/USAGE.md) • [PERFORMANCE](./docs/reference/PERFORMANCE.md) | API reference, benchmarks, usage guide |
| **🎯 Guides** | [SEMANTIC SEARCH](./docs/guides/SEMANTIC_SEARCH.md) • [MULTI-COLLECTION](./docs/guides/MULTI_COLLECTION_GUIDE.md) • [FILE WATCHER](./docs/guides/FILE_WATCHER_GUIDE.md) | Advanced feature guides |
| **🏗️ Architecture** | [ARCHITECTURE](./docs/architecture/ARCHITECTURE.md) • [DATA MODELS](./docs/architecture/DATA_MODELS.md) • [TOKEN MGMT](./docs/architecture/TOKEN_MANAGEMENT.md) | System design, technical deep-dives |
| **👨💻 Development** | [CONTRIBUTING](./docs/development/CONTRIBUTING.md) • [TESTING](./docs/development/TESTING.md) • [ROADMAP](./docs/development/STATUS_AND_ROADMAP.md) | For contributors |
| **📦 Project** | [CHANGELOG](./docs/project/CHANGELOG.md) • [CODE OF CONDUCT](./docs/project/CODE_OF_CONDUCT.md) | Release notes, governance |
| **📝 Other** | [GLOSSARY](./docs/GLOSSARY.md) | Terms & acronyms |
**New to CodeWeaver?** Start with [QUICKSTART.md](./docs/getting-started/QUICKSTART.md) (5 minutes) or [DEVELOPER_WORKFLOW.md](./docs/getting-started/DEVELOPER_WORKFLOW.md) (20 minutes).
---
## 📦 Current Features (Phase 1 + 2 + 3 + 4 Complete)
### ✅ Implemented
**Agents:**
- **Project Metadata Agent** 🆕 - Multi-language project metadata extraction with plugin architecture
- **Gradle**: Java version, dependencies, plugins, modules
- **npm**: TypeScript/JavaScript, package manager detection, scripts, workspaces
- **Auto-detection**: Automatically detects project type(s)
- **Unified Schema**: Language-agnostic metadata format
- **Extensible**: Easy to add new build systems (pip, Maven, Cargo, etc.)
- **System Check Agent** 🆕 - Dependency validation and system health checks
- **Critical**: Node.js (>=18), Git (>=2.0) - required for core features
- **Optional**: Python (>=3.8), Gradle (>=7.0), Maven (>=3.6)
- **Auto-check**: Quick startup validation in CLI mode
- **Doctor Command**: Full system diagnostic with recommendations
- **Cache Agent** - Content-addressable caching with SHA-256 hashing
- **Snippets Agent** - Token-efficient file reading with line ranges
- **Symbols Agent** - Multi-language symbol extraction with plugin architecture 🆕
- **Java**: Classes, Interfaces, Enums, Records, Annotation Types, Sealed Classes, Module System
- **TypeScript**: Classes, Interfaces, Types, Enums, Functions, Generics, Decorators, Namespaces
- **JavaScript**: Classes, Functions, Arrow Functions, Async/Await, ES6+ features
- **Markdown**: Headers as Sections, Local Links as References, Code Blocks
- **Python** 🆕: Classes, Functions, Methods, Decorators, Type Hints, Async/Await
- Methods with parameters, generics, and annotations/decorators
- Fields/Properties with modifiers and visibility
- Constructors, nested types, enum constants
- Language-tagged symbols for easy filtering
- **Search Agent** - Keyword and pattern search with file filtering
- **Analysis Agent** - Cyclomatic complexity, LOC metrics, code quality
- **VCS Agent** - Git operations (status, diff, blame, log, branches, compare)
- **Semantic Index Agent** - LanceDB vector search with multi-collection support 🆕
- **File Watcher Agent** - Automatic incremental index updates on file changes 🆕
- **Symbol Storage** - In-memory symbol index with JSON Lines persistence
**MCP Tools (19 total):**
*File & Project:*
- `project.meta` - Get unified project metadata (auto-detects: Gradle, npm, pip, Maven, etc.)
- Multi-language support with plugin architecture
- Optional `projectType` parameter for specific extraction
- `file.read` - Read file with optional token limit (default: 10000)
- `file.readRange` - Read specific line ranges (1-indexed, inclusive)
- `file.readWithNumbers` - Read file with line numbers for reference
*Symbols:*
- `symbols.index` - Index entire project and extract symbols
- `symbols.find` - Find symbols by name (case-insensitive substring)
- `symbols.findByKind` - Find symbols by kind (class/method/field/constructor)
- `symbols.get` - Get symbol details by qualified name
*Search:*
- `search.keyword` - Search for keyword in files (grep-like)
- `search.files` - Find files by name pattern (glob-like: *.java)
*Analysis:*
- `analysis.file` - Analyze single file for complexity and metrics
- `analysis.project` - Analyze entire project for statistics
*Version Control:*
- `vcs.status` - Get Git repository status
- `vcs.diff` - Get diff for file(s)
- `vcs.blame` - Get Git blame information for file
- `vcs.log` - Get commit history
- `vcs.branches` - Get list of all branches
- `vcs.compare` - Compare two branches
*System:*
- `system.check` - Check system dependencies (planned for MCP integration)
**CLI Commands:**
*Info & Files:*
- `codeweaver info` - Display project information
- `codeweaver file read <path> [--limit N] [--numbers]` - Read files
- `codeweaver file range <path> <start> <end>` - Read line ranges
- `codeweaver file context <path> <line> [-c N]` - Get context around line
*Symbols:*
- `codeweaver symbols index` - Index project and extract symbols
- `codeweaver symbols find <name>` - Find symbols by name
- `codeweaver symbols get <qualifiedName>` - Get symbol details
- `codeweaver symbols list <kind>` - List all symbols of a kind
*Search:*
- `codeweaver search keyword <keyword> [-i] [-m N] [-c N] [-e .ext]` - Keyword search
- `codeweaver search files <pattern>` - Find files by pattern
- `codeweaver search semantic <query> [--index] [-c collection] [-l N]` - Semantic search 🆕
*Analysis:*
- `codeweaver analysis file <path>` - Analyze file complexity and metrics
- `codeweaver analysis project [--top N]` - Analyze project statistics
- `codeweaver analysis complexity <path>` - Show complexity breakdown
*Version Control:*
- `codeweaver vcs status` - Show Git repository status
- `codeweaver vcs diff [file]` - Show diff for file(s)
- `codeweaver vcs blame <file> [-l <range>]` - Show Git blame
- `codeweaver vcs log [-n N] [--since] [--author]` - Show commit history
- `codeweaver vcs branches` - List all branches
- `codeweaver vcs compare <base> <compare>` - Compare two branches
*File Watching:* 🆕
- `codeweaver watch [--debounce N] [--code-only] [--docs-only]` - Watch files and auto-update index
*System Check:* 🆕
- `codeweaver doctor` - Check system dependencies (Node.js, Git, Python, Gradle, Maven)
- `codeweaver doctor --quick` - Quick check (only critical dependencies)
**Infrastructure:**
- Auto-detection (stdio = MCP mode, TTY = CLI mode)
- Progress tracking (JSON Lines format to `.codeweaver/progress.jsonl`)
- Checkpoint/resume capability
- TypeScript strict mode, ESM modules
- Vitest test framework (73 tests passing)
---
## 🏗️ Architecture
### Multi-Agent System
```mermaid
graph TB
CLI[CLI Interface<br/>7 Command Groups] --> SERVICE[CodeWeaverService]
MCP[MCP Server<br/>19 Tools] --> SERVICE
SERVICE --> DISC[Discovery Agent]
SERVICE --> CACHE[Cache Agent]
SERVICE --> SNIP[Snippets Agent]
SERVICE --> SYM[Symbols Agent]
SERVICE --> SEARCH[Search Agent]
SERVICE --> ANALYSIS[Analysis Agent]
SERVICE --> SEMANTIC[Semantic Index Agent]
SERVICE --> WATCHER[File Watcher Agent]
SERVICE --> VCS[VCS Agent]
SERVICE --> STORE[Symbol Storage]
DISC --> GRADLE[Gradle Parser]
CACHE --> SHA[SHA-256 Hashing]
SNIP --> TOKEN[Token Counter]
SYM --> PLUGINREG[Plugin Registry]
PLUGINREG --> JAVAPLUGIN[Java Plugin<br/>java-parser]
PLUGINREG --> TSPLUGIN[TypeScript Plugin<br/>typescript-estree]
PLUGINREG --> JSPLUGIN[JavaScript Plugin<br/>typescript-estree]
PLUGINREG --> MDPLUGIN[Markdown Plugin<br/>remark]
PLUGINREG --> PYPLUGIN[Python Plugin<br/>tree-sitter WASM]
SEARCH --> REGEX[Regex Matching]
ANALYSIS --> COMPLEXITY[Cyclomatic<br/>Complexity]
SEMANTIC --> LANCEDB[LanceDB<br/>Vector Search]
SEMANTIC --> ONNX[ONNX Runtime<br/>Embeddings]
WATCHER --> CHOKIDAR[Chokidar<br/>File Watching]
WATCHER --> SEMANTIC
VCS --> GIT[Git Operations]
STORE --> JSONL[JSON Lines]
style SERVICE fill:#e1f5ff
style CLI fill:#d4edda
style MCP fill:#fff3cd
style SYM fill:#cfe2ff
style SEARCH fill:#cfe2ff
style ANALYSIS fill:#cfe2ff
style SEMANTIC fill:#fff3cd
style WATCHER fill:#fff3cd
style VCS fill:#cfe2ff
```
### Directory Structure
```
src/
├── index.ts # Main entry (auto-detection)
├── cli/
│ ├── index.ts # CLI entry point
│ └── commands/
│ ├── info.ts # Info command
│ ├── file.ts # File commands
│ ├── symbols.ts # Symbols commands (Phase 2)
│ ├── search.ts # Search commands (Phase 2)
│ └── analysis.ts # Analysis commands (Phase 3)
├── mcp/
│ ├── index.ts # MCP entry point
│ ├── server.ts # MCPServer class
│ └── tools.ts # Tool registration (12 tools)
├── core/
│ ├── service.ts # Shared business logic
│ ├── agents/
│ │ ├── discovery.ts # Gradle analysis
│ │ ├── cache.ts # Caching
│ │ ├── snippets.ts # File reading
│ │ ├── symbols.ts # Multi-language symbol extraction (Phase 2)
│ │ ├── search.ts # Keyword/pattern search (Phase 2)
│ │ ├── analysis.ts # Complexity analysis (Phase 3)
│ │ ├── semantic.ts # Vector search (Phase 4)
│ │ ├── vcs.ts # Git operations (Phase 4)
│ │ └── watcher.ts # File watching (Phase 4)
│ ├── language/
│ │ ├── plugin.ts # LanguagePlugin interface
│ │ ├── detector.ts # Language detection
│ │ ├── registry.ts # Plugin registry
│ │ └── plugins/
│ │ ├── java/
│ │ │ ├── index.ts # JavaLanguagePlugin
│ │ │ ├── parser.ts # java-parser wrapper
│ │ │ └── extractor.ts # Java symbol extraction
│ │ └── typescript/
│ │ ├── index.ts # TypeScript/JavaScriptLanguagePlugin
│ │ ├── parser.ts # typescript-estree wrapper
│ │ └── extractor.ts # TS/JS symbol extraction
│ └── storage/
│ └── json-symbol-store.ts # Symbol index
├── types/
│ ├── mcp.ts
│ ├── progress.ts
│ ├── project.ts
│ ├── cache.ts
│ ├── symbols.ts
│ └── analysis.ts # Analysis types (Phase 3)
└── utils/
├── progress-writer.ts # Progress tracking
└── mode-detector.ts # CLI vs MCP detection
tests/
├── unit/ # 184 passing tests
│ ├── mcp/server.test.ts # 6 tests
│ ├── agents/
│ │ ├── discovery.test.ts # 4 tests
│ │ ├── cache.test.ts # 5 tests
│ │ ├── snippets.test.ts # 7 tests
│ │ ├── symbols.test.ts # 23 tests (Java)
│ │ ├── search.test.ts # 11 tests
│ │ ├── analysis.test.ts # 11 tests
│ │ ├── semantic.test.ts # Tests for semantic search
│ │ ├── vcs.test.ts # Tests for VCS operations
│ │ └── watcher.test.ts # Tests for file watcher
│ ├── language/
│ │ ├── detector.test.ts # Language detection tests
│ │ ├── registry.test.ts # Plugin registry tests
│ │ ├── java.test.ts # Java plugin tests
│ │ └── typescript.test.ts # 21 tests (TypeScript/JavaScript)
│ └── storage/
│ └── json-symbol-store.test.ts # 5 tests
├── integration/ # 12 passing tests
│ ├── smoke.test.ts # 5 tests
│ └── multi-language.test.ts # 12 tests (Multi-Language Integration)
└── fixtures/
├── gradle-projects/simple/ # Gradle test fixtures
├── java/ # Java test files
└── typescript/ # TypeScript/JavaScript test files
```
---
## 📖 Usage
### As CLI Tool
**Project & Files:**
```bash
# Show project information
codeweaver info
# Read entire file
codeweaver file read src/core/service.ts
# Read file with line numbers
codeweaver file read src/core/service.ts --numbers
# Read file with token limit
codeweaver file read src/core/service.ts --limit 500
# Read specific lines (1-indexed, inclusive)
codeweaver file range src/core/service.ts 10 20
# Get context around line (default: ±5 lines)
codeweaver file context src/core/service.ts 42
codeweaver file context src/core/service.ts 42 --context 10
```
**Symbols (Phase 2):**
```bash
# Index entire project
codeweaver symbols index
# Find symbols by name (case-insensitive)
codeweaver symbols find "UserService"
codeweaver symbols find "get" # Finds all getXxx methods
# Get specific symbol by qualified name
codeweaver symbols get "com.example.UserService"
codeweaver symbols get "com.example.UserService#findById"
# List all symbols of a kind
codeweaver symbols list class
codeweaver symbols list method
codeweaver symbols list field
```
**Search (Phase 2):**
```bash
# Search for keyword
codeweaver search keyword "TODO"
codeweaver search keyword "processData"
# Case-insensitive search
codeweaver search keyword "exception" --case-insensitive
codeweaver search keyword "exception" -i
# Search with context lines
codeweaver search keyword "TODO" --context 3 -c 3
# Limit results
codeweaver search keyword "public" --max-results 10 -m 10
# Filter by file extensions
codeweaver search keyword "interface" --extensions .java .ts -e .java -e .ts
# Find files by pattern
codeweaver search files "*.java"
codeweaver search files "*Test.java"
codeweaver search files "User*.ts"
```
### As MCP Server
#### 1. Configure MCP Client
Add to your MCP configuration (e.g., Claude Desktop):
```json
{
"mcpServers": {
"codeweaver": {
"command": "node",
"args": [
"/absolute/path/to/mcp-workbench/dist/index.js",
"--mcp"
],
"cwd": "/path/to/your/java/project"
}
}
}
```
Or use npm:
```json
{
"mcpServers": {
"codeweaver": {
"command": "npm",
"args": ["run", "dev", "--", "--mcp"],
"cwd": "/absolute/path/to/mcp-workbench"
}
}
}
```
#### 2. Available MCP Tools (10 total)
**Project & Files:**
**`project.meta`** - Get project metadata
```typescript
// Input: {} (no parameters)
// Output: ProjectMetadata
{
"name": "my-project",
"version": "1.0.0",
"javaVersion": "21",
"gradleVersion": "8.5",
"modules": [...],
"dependencies": [...],
"plugins": [...]
}
```
**`file.read`** - Read file with token limit
```typescript
// Input: { filePath: string, maxTokens?: number }
await mcp.call('file.read', {
filePath: 'src/main/java/com/example/App.java',
maxTokens: 5000
});
```
**`file.readRange`** - Read specific lines
```typescript
// Input: { filePath: string, startLine: number, endLine: number }
await mcp.call('file.readRange', {
filePath: 'src/main/java/com/example/App.java',
startLine: 10,
endLine: 30
});
```
**`file.readWithNumbers`** - Read with line numbers
```typescript
// Input: { filePath: string }
await mcp.call('file.readWithNumbers', {
filePath: 'src/main/java/com/example/App.java'
});
// Output: " 1: package com.example;\n 2: \n 3: public class App { ... }"
```
**Symbols (Phase 2):**
**`symbols.index`** - Index entire project
```typescript
// Input: {} (no parameters)
await mcp.call('symbols.index', {});
// Output: { files: 15, symbols: 234, classes: 12, classList: [...] }
```
**`symbols.find`** - Find symbols by name
```typescript
// Input: { name: string }
await mcp.call('symbols.find', {
name: 'UserService'
});
// Output: SymbolDefinition[]
```
**`symbols.findByKind`** - Find symbols by kind
```typescript
// Input: { kind: 'class' | 'method' | 'field' | 'constructor' }
await mcp.call('symbols.findByKind', {
kind: 'method'
});
// Output: SymbolDefinition[]
```
**`symbols.get`** - Get symbol by qualified name
```typescript
// Input: { qualifiedName: string }
await mcp.call('symbols.get', {
qualifiedName: 'com.example.UserService#findById'
});
// Output: SymbolDefinition
```
**Search (Phase 2):**
**`search.keyword`** - Search for keyword in files
```typescript
// Input: { keyword: string, caseSensitive?: boolean, maxResults?: number, contextLines?: number, fileExtensions?: string[] }
await mcp.call('search.keyword', {
keyword: 'TODO',
caseSensitive: false,
maxResults: 50,
contextLines: 2,
fileExtensions: ['.java', '.ts']
});
// Output: SearchResult[] with file, line, column, content, beforeContext, afterContext
```
**`search.files`** - Find files by pattern
```typescript
// Input: { pattern: string }
await mcp.call('search.files', {
pattern: '*Test.java'
});
// Output: string[] (file paths)
```
---
## 🧪 Testing
```bash
# Run all tests
npm test
# Run tests in CI mode (no watch)
npm test -- --run
# Run specific test file
npm test -- tests/unit/agents/snippets.test.ts
```
**Test Coverage:**
- ✅ MCP Server (6 tests)
- ✅ Discovery Agent (4 tests)
- ✅ Cache Agent (5 tests)
- ✅ Snippets Agent (7 tests)
- ✅ Symbol Storage (5 tests)
- ✅ Symbols Agent (23 tests - Java)
- ✅ Language Plugins (21 tests - TypeScript/JavaScript, 13 tests - Markdown)
- ⚠️ Python Plugin (18 tests - skipped due to WASM config)
- ✅ Search Agent (11 tests)
- ✅ Analysis Agent (11 tests)
- ✅ Semantic Agent (tests for vector search)
- ✅ VCS Agent (tests for Git operations)
- ✅ File Watcher Agent (tests for file watching)
- ✅ Integration Tests (17 tests: 5 smoke + 12 multi-language)
- **Total: 256 passing (100%)**
---
## 🔧 Development
### Prerequisites
- **Node.js** >= 20.0.0
- **TypeScript** 5.7+
- **Java** JDK 21 (for target projects)
- **Gradle** (optional, wrapper preferred)
### Setup
```bash
# Clone repository
git clone <repository-url>
cd mcp-workbench
# Install dependencies
npm install
# Build
npm run build
# Development mode (with auto-reload)
npm run build:watch
# Run in dev mode (no build required)
npm run dev
```
### Scripts
```bash
npm run build # Compile TypeScript
npm run build:watch # Watch mode
npm run dev # Run with tsx (no build)
npm test # Run tests (watch mode)
npm run lint # ESLint
npm run format # Prettier
npm run clean # Remove dist & cache
npm run validate-links # Validate markdown links 🆕
```
**Documentation Tools**:
```bash
npm run validate-links # Validate internal links (~2s)
npm run validate-links:external # Include external links (~30s)
npm run validate-links:verbose # Detailed output
```
See [LINK_VALIDATION.md](./docs/development/LINK_VALIDATION.md) for details.
---
## 📊 Token Efficiency
CodeWeaver is designed to minimize token usage when providing code context to LLMs:
### Strategies
1. **Line Ranges**: Only send requested line ranges, not entire files
2. **Token Limits**: Automatic truncation to configurable limits (default: 10k)
3. **Smart Truncation**: Respects word boundaries when truncating
4. **Token Counting**: Simple heuristic (~4 chars/token) for quick estimates
5. **Context Windows**: Provide minimal context around specific lines
### Token Estimation
| Content Type | Typical Size | Tokens (approx) |
|--------------|--------------|-----------------|
| Small snippet (20 lines) | ~1 KB | ~250 |
| Medium snippet (80 lines) | ~4 KB | ~1000 |
| Large snippet (200 lines) | ~10 KB | ~2500 |
| Project metadata | ~2 KB | ~500 |
**Max Response Size**: 10,000 tokens (~40 KB text)
---
## 🗺️ Roadmap
### ✅ Phase 1: Foundation (Complete - 100%)
- ✅ MCP Server skeleton with tool registration
- ✅ Progress tracking (JSON Lines)
- ✅ Discovery Agent (Gradle metadata)
- ✅ Cache Agent (content-addressable storage)
- ✅ Symbol Storage (JSON Lines persistence)
- ✅ Core Service (shared logic)
- ✅ CLI Interface with commands
- ✅ MCP Interface with stdio
- ✅ Build & Test Setup (32 tests passing)
- ✅ Snippets Agent with token limits
- ✅ Documentation (complete)
- ✅ Integration Tests (5 smoke tests)
### ✅ Phase 2: Indexing (Complete - 100%)
- ✅ Symbols Agent (java-parser, symbol extraction)
- ✅ Search Agent (keyword + pattern search)
- ✅ Project-wide indexing (classes, methods, fields, constructors)
- ✅ Symbol search (by name, kind, qualified name)
- ✅ File search (glob patterns with * and ?)
- ✅ Context search (lines before/after matches)
- ✅ MCP Tools integration (6 new tools)
- ✅ CLI Commands integration (symbols, search)
- ✅ Full test coverage (19 new tests)
- ✅ Documentation update
**Note:** LanceDB semantic search deferred to later phase as enhancement
### ✅ Phase 3: Analysis (Complete - 100%)
- ✅ Analysis Agent (complexity & metrics calculation)
- ✅ Cyclomatic Complexity calculation (if, loops, catch, &&, ||, ?:)
- ✅ Code Metrics (LOC, SLOC, comments, blank lines)
- ✅ Import analysis
- ✅ Method call detection
- ✅ Project-wide statistics (total complexity, average, top N files)
- ✅ MCP Tools integration (2 new tools)
- ✅ CLI Commands integration (analysis)
- ✅ Full test coverage (11 new tests)
- ✅ Documentation update
**Note:** Static analysis tools (SpotBugs, Checkstyle) and Gradle runner deferred
### ✅ Phase 4: VCS Integration (Complete - 100%)
- ✅ VCS Agent (Git operations)
- ✅ Repository status (modified, added, deleted, untracked files)
- ✅ Diff generation (file-level and project-level)
- ✅ Blame information (line-by-line authorship)
- ✅ Commit history (with filtering options)
- ✅ Branch management (list, compare)
- ✅ MCP Tools integration (6 new tools)
- ✅ CLI Commands integration (vcs)
- ✅ Full test coverage (11 new tests)
- ✅ Documentation update
### 📋 Phase 5: Orchestration (Planned)
- Orchestrator Agent (DAG-based pipeline)
- Parallel task execution
- Dependency resolution
---
## 🐛 Troubleshooting
### Tests failing?
```bash
# Clean and reinstall
npm run clean
rm -rf node_modules package-lock.json
npm install
npm test -- --run
```
### Build errors?
```bash
# Check TypeScript version
npx tsc --version # Should be 5.7+
# Rebuild
npm run clean
npm run build
```
### MCP server not responding?
```bash
# Check if running in MCP mode
npm run dev -- --mcp
# Verify stdio transport
echo '{}' | npm run dev -- --mcp
```
### CLI not working?
```bash
# Ensure TTY mode (not piped)
npm run dev -- info
# Check built binary
node dist/index.js info
```
---
## 📝 Progress Tracking
View live progress during implementation:
```bash
# Bash/Git Bash
tail -f .codeweaver/progress.jsonl
# PowerShell
Get-Content .codeweaver\progress.jsonl -Wait
# Read checkpoint
cat .codeweaver/checkpoint.json
```
---
## 🤝 Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass: `npm test -- --run`
5. Follow code style (ESLint + Prettier)
6. Submit a pull request
### Code Style
- **TypeScript Strict Mode**: All type errors must be resolved
- **ESM Modules**: Use `.js` extensions in imports
- **Test-Driven Development**: Write tests first
- **No Unused Variables**: Clean code, no warnings
---
## 📄 License
MIT License - see [LICENSE](./LICENSE)
---
## 📚 Documentation
**Vollständige Dokumentation in [`docs/`](./docs/)**
### 🗺️ Schnellzugriff
**Komplette Navigation:** **[docs/INDEX.md](./docs/INDEX.md)** - Vollständiger Dokumentations-Index mit Navigation nach Rolle
**Beliebte Dokumente:**
- **[DEVELOPER_WORKFLOW.md](./docs/getting-started/DEVELOPER_WORKFLOW.md)** - 🚀 **START HERE!** Complete Developer Workflow (All 19 MCP tools in action)
- **[QUICKSTART.md](./docs/getting-started/QUICKSTART.md)** - ⚡ 5-Minuten Quick-Start Guide
- **[API.md](./docs/reference/API.md)** - 📚 Complete API Reference (alle 19 MCP Tools)
- **[PERFORMANCE.md](./docs/reference/PERFORMANCE.md)** - ⚡ Performance Benchmarks & Scalability
- **[SEMANTIC_SEARCH.md](./docs/guides/SEMANTIC_SEARCH.md)** - 🔥 Semantic Search Guide mit Workflows
- **[ARCHITECTURE.md](./docs/architecture/ARCHITECTURE.md)** - 🏗️ System-Architektur (Dual-Mode, Multi-Agent)
- **[GLOSSARY.md](./docs/GLOSSARY.md)** - 📖 Glossar aller Begriffe & Akronyme
### 🔗 Externe Links
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP Specification
---
## 🎯 Current Status
**Alpha Release v0.1.0** ⚠️
✅ **Working Features:**
- **MCP Server** with 19 tools (project, files, symbols, search, analysis, vcs)
- **CLI** with 7 command groups (includes watch mode)
- **Multi-Language Support** - Java, TypeScript, JavaScript, Markdown, Python with plugin architecture
- **Semantic Search** with ONNX Runtime optimizations
- **Multi-Collection Support** (Code + Docs)
- **File Watcher** for automatic index updates
- **Symbol Extraction** - Complete support for Java, TypeScript, JavaScript, Markdown, and Python
- **Code Quality Analysis** - Cyclomatic complexity, LOC metrics
- **Git Integration** - Status, diff, blame, log, branches
- **291 tests passing** (100% - all features tested)
⚠️ **Known Limitations:**
- Performance varies on large codebases (>10k files)
- Semantic search memory usage can be high
- File watcher may miss rapid changes
- Documentation is incomplete
- Breaking changes expected in future releases
🔮 **Planned Improvements:**
- ~~Python WASM configuration~~ ✅ COMPLETED
- GPU acceleration for semantic search
- Better error messages
- More language support (Go, Rust, C#, etc.)
- Performance optimizations
- Comprehensive documentation
---
## 💡 Philosophy
**CodeWeaver** follows these principles:
1. **Token Efficiency First** - Never overwhelm LLMs with entire files
2. **Zero Native Dependencies** - Pure Node.js for portability
3. **Test-Driven Development** - Tests before implementation
4. **Dual Interface** - Same codebase serves CLI and MCP
5. **Progressive Enhancement** - Working foundation, build up from there
---
Built with ❤️ for the LLM-assisted development workflow.
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues