File Context MCP Server with Recruitment Assistant

A comprehensive Model Context Protocol (MCP) server with integrated Claude AI recruitment assistant. This application provides AI-powered file operations with a specialized focus on candidate evaluation and technical assessment, featuring secure API endpoints and professional profile management.

Features

🤖 AI Recruitment Assistant

• Claude AI Integration: Powered by Anthropic's Claude for intelligent candidate evaluation
• Professional Profile Analysis: Specialized context using Yonatan Ayalon's 15+ years of senior engineering experience
• Technical Assessment: Expert evaluation of candidates across frontend, backend, and full-stack technologies
• Secure API Access: CORS-protected endpoints for third-party integrations

🔧 File System Tools

1. read_file - Read any file from the local filesystem

   • Input: path (string) - File path to read
   • Returns: File content with syntax highlighting support

2. list_directory - List directory contents with metadata

   • Input: path (string) - Directory path to list
   • Returns: Files and folders with sizes and type indicators

3. search_files - Advanced file pattern matching

   • Input: rootPath (string), pattern (string) - Search location and pattern
   • Returns: Matching file paths across directory tree

4. analyze_folder - Comprehensive project analysis

   • Input: path (string) - Folder to analyze
   • Returns: Structure analysis, file types, and project insights

🌐 API Endpoints

• /api/chat - Claude AI chat interface with file context
• /api/tools - Direct file operations API
• /api/evaluate-candidate - Public recruitment evaluation endpoint
• CORS Security: Restricted to localhost:3000 and https://yonatan-ayalon.com

Quick Start

1. Install Dependencies

npm install

For corporate firewalls: If you're behind a corporate proxy/firewall (like Zscaler), configure npm to use a mirror registry:

# Configure npm to use mirror registry (for corporate firewalls)
npm config set registry https://registry.npmmirror.com

2. Configure Claude API Key

Set your Anthropic/Claude API key as an environment variable. Create a .env.local file in the project root:

echo "ANTHROPIC_API_KEY=sk-ant-api03-your-actual-api-key-here" > .env.local

Note: This project works exclusively with Anthropic's Claude API. You'll need an API key from Anthropic for full functionality.

Alternatively, set the environment variable directly:

export ANTHROPIC_API_KEY="your-claude-api-key-here"

⚠️ Security Note: The .env.local file is automatically ignored by git to keep your API key secure. The application will run with limited functionality without an API key.

3. Build the Project

npm run build

4. Launch the Application

🚀 Production Server (Recommended)

npm run start:http

Access Points:

• Web Interface: http://localhost:3000
• API Endpoints: http://localhost:3000/api/*
• MCP Server: http://localhost:3000/mcp

🛠️ Development Mode

npm run start:http:prod    # Production build
npm run start             # HTTP server mode
npm run dev              # Development with watch mode

5. Run Tests

npm test                    # Run all tests
npm run test:coverage      # Run tests with coverage report
npm run test:watch         # Run tests in watch mode

Application Interfaces

🎨 Interactive Web UI (Primary Interface)

Access the full-featured web interface at http://localhost:3000

Key Features:

• 🤖 AI Recruitment Assistant: Claude-powered candidate evaluation with professional context
• 🗂️ File Operations Dashboard: Visual file management with drag-and-drop support
• 💬 Natural Language Queries: Ask questions about code, files, and project structure
• 📊 Real-time Analysis: Live project analysis and code insights
• 🔒 Secure API Access: CORS-protected endpoints for third-party integrations
• 📱 Responsive Design: Optimized for desktop, tablet, and mobile devices

🔗 API Endpoints

Chat & AI Features

POST /api/chat              # Claude AI conversation with file context
GET  /api/evaluate-candidate # Public recruitment evaluation endpoint

File Operations

POST /api/tools             # Direct access to all file system tools
                           # Supports: read_file, list_directory, search_files, analyze_folder

CORS Security

• Allowed Origins: http://localhost:3000, https://yonatan-ayalon.com
• Third-party Integration: Use /api/evaluate-candidate for external recruitment tools

💬 Command Line Interfaces

Interactive Terminal Chat

npm run chat                # Claude AI chat in terminal
npm run chat:mock          # Mock mode (no API key required)
npm run local-chat         # Local Ollama integration

MCP Protocol Support

npm run start:stdio        # Standard MCP server mode

Third-Party Integration

🔗 Public API Usage

For external recruitment tools and applications:

// Candidate evaluation endpoint
const response = await fetch('http://localhost:3000/api/evaluate-candidate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Origin': 'https://yonatan-ayalon.com' // Must be from allowed origins
  },
  body: JSON.stringify({
    candidateData: {
      name: "Candidate Name",
      resume: "resume content...",
      portfolio: "portfolio links..."
    },
    evaluationCriteria: ["technical skills", "experience", "culture fit"]
  })
});

const evaluation = await response.json();

🛡️ Security & CORS

• Restricted Access: Only localhost:3000 and https://yonatan-ayalon.com
• API Security: All endpoints protected with CORS validation
• File Access: Limited to markdown files in /api-resources/ directory
• Rate Limiting: Built-in protection against abuse

Testing & Development

🧪 Comprehensive Test Suite

npm test                    # Run all tests
npm run test:coverage      # Coverage report (>90% coverage)
npm run test:watch         # Development watch mode

Test Categories:

• Unit Tests: File operations and API endpoints
• Integration Tests: Claude AI integration and MCP functionality
• Security Tests: CORS, path validation, access controls
• Performance Tests: Large file handling and concurrent operations
• Mock Tests: Offline functionality without API keys

MCP Client Integration

Claude Desktop Configuration

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "file-context-recruitment": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/build/index.js"]
    }
  }
}

VS Code MCP Extension

Configure the VS Code MCP extension with .vscode/mcp.json:

{
  "servers": {
    "file-context-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/yonatan.ayalon/projects/new_app_1/my-mcp/build/index.js"]
    }
  }
}

Alternative: HTTP MCP Mode

For network-based MCP connections:

npm run start:http
# Connect MCP clients to: http://localhost:3000/mcp

Use Cases & Examples

🤖 AI Recruitment Assistant

Candidate Evaluation:

• "Evaluate this candidate's React experience based on their portfolio"
• "Assess technical skills for a senior frontend position"
• "Compare multiple candidates for full-stack developer role"

Technical Assessment:

• "Review this code sample and provide feedback"
• "What's missing from this candidate's skillset for our team?"
• "Rate this developer's experience with modern JavaScript frameworks"

🗂️ File Operations

Project Analysis:

• "Analyze this codebase and identify the tech stack"
• "What's the overall architecture of this application?"
• "Find all configuration files in this project"

Code Review:

• "Read the main components and explain the application structure"
• "Search for all test files and assess coverage"
• "Analyze the API endpoints in this project"

🔍 Natural Language Queries

Simple Operations:

• "What files are in the src directory?"
• "Read the package.json and explain the dependencies"
• "Find all TypeScript files with interfaces"

Complex Analysis:

• "Compare the frontend and backend code quality"
• "Identify potential security issues in the codebase"
• "Suggest improvements for performance optimization"

Security Features

🛡️ API Security

• CORS Protection: Restricted to localhost:3000 and https://yonatan-ayalon.com
• Path Validation: All file paths resolved to prevent directory traversal
• File Access Control: Limited to markdown files in /api-resources/
• Environment Isolation: Development/production mode security controls

🔒 File System Security

• Permission Checks: Read permissions validated before file access
• Recursive Limits: Directory analysis depth limited to prevent loops
• Hidden File Filtering: Automatic exclusion of system/hidden files
• Sanitized Paths: All inputs sanitized and validated

Development

📁 Project Structure

├── api/
│   └── index.js          # Express API server with Claude integration
├── src/
│   ├── index.ts          # Main MCP server implementation
│   ├── http-server.ts    # HTTP server with UI
│   ├── chat-interface.ts # Terminal chat interface
│   ├── local-chat.ts     # Local Ollama integration
│   └── file-operations.ts # Core file system tools
├── api-resources/
│   ├── yonatan-profile.md # Professional recruitment profile
│   └── projects-achievements.md # Technical achievements
├── build/                # Compiled JavaScript output
├── ui/                   # Web interface assets
├── tests/               # Comprehensive test suite
└── coverage/           # Test coverage reports

🔧 Available Scripts

Production:

• npm run build - Build server and UI components
• npm run start:http - Launch production HTTP server
• npm run start:http:prod - Production mode with optimizations

Development:

• npm run dev - TypeScript watch mode
• npm run chat - Terminal chat interface
• npm run local-chat - Local AI integration

Testing:

• npm test - Run complete test suite
• npm run test:coverage - Generate coverage reports
• npm run test:watch - Interactive test development

🔍 Testing & Debugging

Use the MCP Inspector for protocol debugging:

npx @modelcontextprotocol/inspector node build/index.js

Technical Specifications

🏗️ Architecture

• Core Protocol: Model Context Protocol (MCP) v1.24.2
• Transport Layers: STDIO, HTTP REST API
• Backend: Node.js + Express with TypeScript
• Frontend: Vanilla JavaScript with modern CSS
• AI Integration: Anthropic Claude API
• Database: File-based (markdown profiles)

🔧 Technology Stack

• Runtime: Node.js 16+
• Language: TypeScript 5+
• Framework: Express.js with CORS
• Testing: Jest with TypeScript support
• Build: Native TypeScript compiler
• Security: Path validation, CORS, environment controls

📋 System Requirements

• Node.js: 16.0.0 or higher
• Memory: 512MB RAM minimum
• Storage: 100MB for dependencies and build artifacts
• Network: Internet access for Claude API (optional for file operations)
• OS: macOS, Linux, or Windows with Node.js support

🌐 Deployment

• Local Development: npm run start:http
• Production Ready: Environment variable configuration
• Docker Support: Containerization ready
• Cloud Deployment: Compatible with Vercel, Heroku, AWS

License

MIT License - Open source recruitment assistant and file context server.

---

Support & Documentation

• MCP Protocol: Model Context Protocol Documentation
• Claude API: Anthropic API Documentation
• Issues: Create GitHub issues for bug reports and feature requests
• Professional Contact: Integration support available through yonatan-ayalon.com

🚀 Quick Deploy

1. Clone & Install: git clone [repo] && npm install
2. Configure API: Add ANTHROPIC_API_KEY to .env.local
3. Build & Run: npm run build && npm run start:http
4. Access: Open http://localhost:3000