# CodeWeaver MCP Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
**Transform your entire codebase into a single, AI-readable Markdown document through the Model Context Protocol.**
English | [简体中文](README.zh-CN.md)
CodeWeaver MCP Server brings powerful code packaging capabilities to AI assistants like Claude Code. It converts complex project structures into clean, navigable Markdown files - perfect for code reviews, documentation, AI analysis, and sharing with teams.
## Why CodeWeaver MCP?
### 🚀 Seamless AI Integration
- **Native MCP Protocol**: Works out-of-the-box with Claude Code and other MCP-compatible AI assistants
- **Zero Context Switching**: Access codebase packaging directly from your AI workflow
- **Instant Results**: Get Markdown output immediately or save to file
### 📦 Complete Codebase Visibility
- **Full Structure Capture**: Beautiful tree-view of your entire project hierarchy
- **All Code Included**: Every file's content embedded with proper syntax highlighting
- **Smart Filtering**: Respects `.gitignore` and supports custom ignore patterns
### 💡 Perfect for Multiple Use Cases
**For AI Analysis**
- Feed entire codebases to AI models (ChatGPT, Claude, etc.)
- Enable comprehensive code understanding without manual file sharing
- Perfect for code reviews and refactoring discussions
**For Documentation**
- Generate instant project snapshots
- Create shareable codebase documentation
- Archive project states at key milestones
**For Team Collaboration**
- Share complete project context with teammates
- Onboard new developers faster
- Facilitate remote code discussions
**For Code Reviews**
- Package pull requests with full context
- Review entire features in one document
- Track code changes across multiple files
## Features
### 🎯 Pure TypeScript Implementation
- **No External Dependencies**: Built entirely in TypeScript - no Go, Python, or other runtimes required
- **Fast & Lightweight**: Efficient file scanning and processing
- **Cross-Platform**: Works on macOS, Linux, and Windows
### 🛠️ Powerful Customization
- **Flexible Filtering**: Include/exclude files with glob patterns
- **Gitignore Support**: Automatically respects your `.gitignore` rules
- **Custom Patterns**: Add project-specific ignore patterns
- **Multiple Output Modes**: Return content directly or save to file
### 📝 Smart Markdown Output
- **Syntax Highlighting**: Automatic language detection for 20+ programming languages
- **Clean Formatting**: Professional tree structure using box-drawing characters
- **Organized Layout**: Logical file ordering (directories first, alphabetical)
- **Relative Paths**: Clear file location references
## Installation
### Prerequisites
- Node.js 18 or later
- npm or yarn
### Quick Install
```bash
# Clone and build
git clone https://github.com/yourusername/codeweaver-mcp-server.git
cd codeweaver-mcp-server
npm install
npm run build
```
### Add to Claude Code
```bash
claude mcp add codeweaver node /absolute/path/to/codeweaver-mcp-server/dist/index.js
```
Or manually add to `~/.claude/config.json`:
```json
{
"mcpServers": {
"codeweaver": {
"command": "node",
"args": ["/absolute/path/to/codeweaver-mcp-server/dist/index.js"]
}
}
}
```
## Usage
### Basic Usage
Pack current directory:
```typescript
codeweaver_pack_codebase({
path: "."
})
```
### Save to File
```typescript
codeweaver_pack_codebase({
path: "./src",
output: "codebase.md"
})
```
### Include Gitignored Files
```typescript
codeweaver_pack_codebase({
path: ".",
include_gitignored: true
})
```
### Custom Ignore Patterns
```typescript
codeweaver_pack_codebase({
path: ".",
ignore_patterns: ["*.log", "tmp/*", "*.tmp"]
})
```
## Output Format
CodeWeaver generates clean, structured Markdown:
```markdown
# project-name
## Directory Structure
```
├── src
│ ├── index.ts
│ └── utils.ts
└── package.json
```
## Files
### src/index.ts
```typescript
// Full file content with syntax highlighting
import { helper } from './utils';
...
```
### src/utils.ts
```typescript
// Full file content
export function helper() { ... }
```
```
## Supported Languages
Automatic syntax highlighting for:
- TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`)
- Python (`.py`)
- Go (`.go`)
- Rust (`.rs`)
- Java (`.java`)
- C/C++ (`.c`, `.cpp`, `.h`, `.hpp`)
- C# (`.cs`)
- Ruby (`.rb`)
- PHP (`.php`)
- Swift (`.swift`)
- Kotlin (`.kt`)
- SQL (`.sql`)
- Shell (`.sh`)
- YAML (`.yaml`, `.yml`)
- JSON (`.json`)
- XML (`.xml`)
- HTML (`.html`)
- CSS (`.css`)
- Markdown (`.md`)
## Default Ignore Patterns
CodeWeaver automatically skips:
- `node_modules/`
- `.git/`
- `dist/` and `build/`
- `.next/` and `.nuxt/`
- `vendor/`
- Python virtual environments (`venv/`, `.venv/`, `__pycache__/`)
- System files (`.DS_Store`, `Thumbs.db`)
## Real-World Examples
### Example 1: Share Code with ChatGPT
```typescript
// Pack your project
codeweaver_pack_codebase({
path: "./my-app",
output: "my-app-context.md"
})
// Copy the Markdown file content and paste into ChatGPT
// Now ChatGPT can see your entire codebase!
```
### Example 2: Code Review Documentation
```typescript
// Pack only source code
codeweaver_pack_codebase({
path: "./src",
ignore_patterns: ["*.test.ts", "*.spec.ts"],
output: "review-package.md"
})
```
### Example 3: Project Snapshot
```typescript
// Capture complete project state
codeweaver_pack_codebase({
path: ".",
output: `snapshot-${new Date().toISOString()}.md`
})
```
## API Reference
### `codeweaver_pack_codebase`
**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `path` | string | ✅ Yes | - | Directory path to pack |
| `output` | string | ❌ No | - | Output file path (returns content if omitted) |
| `include_gitignored` | boolean | ❌ No | `false` | Include files listed in `.gitignore` |
| `ignore_patterns` | string[] | ❌ No | `[]` | Additional glob patterns to ignore |
**Returns:**
- If `output` specified: Success message with file path and size
- If `output` omitted: Complete Markdown content
**Error Handling:**
- `"Error: Path does not exist"` - Invalid directory path
- `"Error: Path is not a directory"` - Path points to a file
- Binary files automatically skipped with notice
## Development
### Build from Source
```bash
npm install
npm run build
```
### Development Mode
```bash
npm run dev
```
### Clean Build
```bash
npm run clean
npm run build
```
## Why Choose CodeWeaver MCP?
✅ **For AI-First Workflows**: Built specifically for AI tools, unlike generic file packers
✅ **Zero Configuration**: Works immediately with sensible defaults
✅ **Professional Output**: Clean, readable Markdown that humans and AI love
✅ **Modern Stack**: Pure TypeScript, no legacy dependencies
✅ **Active Development**: Regularly updated with new features
✅ **MIT Licensed**: Free for personal and commercial use
## Comparison with Alternatives
| Feature | CodeWeaver MCP | Command-line tools | VSCode Extensions |
|---------|----------------|-------------------|-------------------|
| AI Integration | ✅ Native MCP | ❌ Manual copy-paste | ⚠️ Limited |
| Zero Config | ✅ Yes | ❌ Complex flags | ✅ Yes |
| Cross-Platform | ✅ Yes | ⚠️ Varies | ⚠️ VSCode only |
| Real-time Use | ✅ Yes | ❌ No | ⚠️ Limited |
| TypeScript Native | ✅ Yes | ❌ Various | ⚠️ Varies |
## Contributing
Contributions welcome! Please feel free to submit issues or pull requests.
## License
MIT License - see [LICENSE](LICENSE) file for details
## Acknowledgments
Inspired by the original [CodeWeaver](https://github.com/tesserato/CodeWeaver) project and adapted for the Model Context Protocol ecosystem.
---
**Made with ❤️ for the AI development community**
