MCP Source Server

🚀 MCP Server

Leverage your existing AI assistants for seamless coding by setting up this server that enables intelligent code analysis and correction suggestions.

🚀 Quick Start

Installation

# Clone the repository
git clone git@hgithub.com/Chakotay-Lee/mcp-source-server
cd mcp-source-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Claude Desktop Configuration

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "source-code-server": {
      "command": "node",
      "args": ["/path/to/your/mcp-source-server/dist/index.js"],
      "env": {
        "MCP_WORKSPACE_DIR": "/path/to/your/workspace"
      }
    }
  }
}

Replace /path/to/your/mcp-source-server with the actual path to this project, and /path/to/your/workspace with your desired workspace directory.

✨ Features

Core File Operations

• Read Files: Securely read source code files with size limits.
• Write Files: Create and update files with optional backup.
• List Files: Browse directory contents with metadata.
• Stream Writing: Efficient handling of large file writes.

🆕 Enhanced Operations (v0.2.1)

• Delete Files: Safely delete files with automatic backup.
• Rename/Move Files: Rename files or move them between directories.
• Partial Write: LLM-optimized feature to update specific file sections without rewriting entire files.

🔒 Security Features

• Directory Traversal Protection: Prevents access outside workspace.
• File Extension Whitelist: Only allows approved file types.
• Path Blacklisting: Blocks access to sensitive directories.
• Size Limits: Prevents excessive file operations.
• Concurrent Operation Limits: Protects system resources.

📋 Available Tools

Basic Operations

• read_source_file - Read file content.
• write_source_file - Write content to file.
• list_source_files - List files in directory.
• stream_write_source_file - Stream write for large files.

🆕 Enhanced Operations

• delete_source_file - Delete file with backup option.
• rename_source_file - Rename or move file with backup.
• partial_write_source_file - Update specific file content (LLM optimized).

Utility

• get_server_stats - Get server status and statistics.

🔧 Configuration

Environment Variables

• MCP_WORKSPACE_DIR: Set the workspace directory (default: ./workspace).

Security Configuration

The server includes built-in security configurations:

Allowed File Extensions

• Programming: .js, .ts, .jsx, .tsx, .py, .cpp, .c, .h, etc.
• Web: .html, .css, .scss, .json, .xml, .yaml, etc.
• Documentation: .md, .txt, .rst, .adoc.
• Templates: .template, .example, .sample, .config.
• No extension: Dockerfile, Makefile, .gitignore, etc.

Blacklisted Paths

• .. - Directory traversal prevention.
• .git/ - Git repository files.
• node_modules/ - Dependencies directory.
• .env. - Environment files (except templates).
• secrets/ - Secrets directory.
• System files (.DS_Store, Thumbs.db).

💻 Usage Examples

Basic Usage

// Read a file
await callTool('read_source_file', { filePath: 'src/index.js' });

// Write a file
await callTool('write_source_file', {
  filePath: 'src/new-file.js',
  content: 'console.log("Hello World");',
  createBackup: true
});

// List files
await callTool('list_source_files', { dirPath: 'src' });

Advanced Usage

// Delete a file (with backup)
await callTool('delete_source_file', {
  filePath: 'old-file.js',
  createBackup: true
});

// Rename/move a file
await callTool('rename_source_file', {
  oldPath: 'old-name.js',
  newPath: 'src/new-name.js',
  createBackup: true
});

// LLM-optimized partial update
await callTool('partial_write_source_file', {
  filePath: 'utils.js',
  oldContent: 'function oldFunction() { return "old"; }',
  newContent: 'function newFunction() { return "updated"; }'
});

🛡️ Security Notes

Allowed Development Files

✅ .gitignore, .env.template, Dockerfile, Makefile, package.json, tsconfig.json

Protected Files

🔒 .env, .env.local, .env.production, .git/config, node_modules/, secrets/

🧪 Testing

# Run all tests
npm test

# Run specific test
npm test -- --testNamePattern="should allow development configuration files"

# Run with coverage
npm run test:coverage

🔄 Backup System

The server automatically creates backups in the .backups directory with timestamps:

• Format: filename.timestamp.backup
• Location: workspace/.backups/
• Automatic cleanup recommended.

📊 Performance Features

• Concurrent Operation Limits: Prevents system overload.
• File Size Limits: Default 10MB per file.
• LLM Optimization: Partial write reduces file I/O for small changes.
• Stream Processing: Efficient handling of large files.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests for new functionality.
5. Ensure all tests pass.
6. Submit a pull request.

📄 License

[Your License Here]

🆕 Changelog

v0.2.1

• ✨ Added file deletion functionality.
• ✨ Added file rename/move functionality.
• ✨ Added LLM-optimized partial write functionality.
• 🔧 Fixed .env.template file access.
• 🔧 Enhanced security with precise pattern matching.
• 🧪 Comprehensive test suite (21 tests).

v0.1.0

• 🎉 Initial release with basic file operations.
• 🔒 Security features and path validation.
• 📚 MCP protocol implementation.