# 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

```bash
npm install
```

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

```bash
# 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:

```bash
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](https://console.anthropic.com/) for full
functionality.

Alternatively, set the environment variable directly:

```bash
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

```bash
npm run build
```

### 4. Launch the Application

#### 🚀 Production Server (Recommended)

```bash
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

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

### 5. Run Tests

```bash
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

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

#### File Operations

```bash
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

```bash
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

```bash
npm run start:stdio        # Standard MCP server mode
```

## Third-Party Integration

### 🔗 **Public API Usage**

For external recruitment tools and applications:

```javascript
// 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**

```bash
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):

```json
{
  "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`:

```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:

```bash
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](https://github.com/modelcontextprotocol/inspector) for
protocol debugging:

```bash
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](https://modelcontextprotocol.io/)
- **Claude API**: [Anthropic API Documentation](https://docs.anthropic.com/)
- **Issues**: Create GitHub issues for bug reports and feature requests
- **Professional Contact**: Integration support available through
  [yonatan-ayalon.com](https://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