CV Recruitment Assistant

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Cloudflare Workers-based MCP (Model Context Protocol) server with **digital signature security**. The project serves as a CV Recruitment Assistant system, providing comprehensive tools for HR professionals and recruitment LLMs to analyze candidate information from Brayan Smith Cordova Tasayco's resume. **All responses are digitally signed** to ensure authenticity and integrity. ## Key Architecture - **Entry Point**: `src/index.ts` - Contains the main `MyMCP` class extending `McpAgent` - **MCP Server**: Named "CV Recruitment Assistant" with **17 specialized tools** for candidate evaluation - **Data Source**: `src/candidate-data.json` - Structured CV data for Brayan Smith Cordova Tasayco - **Crypto Module**: `src/crypto.ts` - **Digital signature system** with RSA-2048 + SHA-256 - **Durable Objects**: `MyMCP` class serves as both the MCP agent and Durable Object - **Routing**: Handles `/sse` and `/mcp` endpoints for different connection types - **Tool Schema**: Uses Zod for runtime type validation of tool parameters - **Security**: All responses digitally signed with timestamp and server ID ## Development Commands - `npm run setup-keys` - Generate cryptographic keys for local development - `npm run dev` - Start local development server with Wrangler (uses .env.local) - `npm run deploy` - Deploy to Cloudflare Workers - `npm run format` - Format code with Biome - `npm run lint:fix` - Fix linting issues with Biome - `npm run type-check` - Run TypeScript type checking - `npm run cf-typegen` - Generate Cloudflare Worker types - `npm test` - Run complete test suite including digital signature validation - `npm run test:mcp` - Run MCP-specific tool tests - `npm run test:crypto` - Run cryptographic function tests - `npm run test:watch` - Run tests in watch mode (auto-restart on changes) ## Available MCP Tools ### Core Information Tools (8 tools) - `get_candidate_profile` - Personal info, contact details, and professional summary - `get_work_experience` - Detailed work experience with achievements and technologies - `get_education_background` - Academic background and current studies - `get_certifications` - Professional certifications with verification links - `get_technical_skills` - Technical, design, and productivity skills categorized - `get_soft_skills` - Soft skills and language proficiencies - `get_languages_interests` - Languages and personal interests - `search_candidate_info` - Search across all candidate data by keyword ### Online Presence Tools (3 tools) - `get_portfolio_website` - Access to candidate's personal portfolio and website - `get_github_profile` - GitHub profile information and certifications - `get_social_networks` - Social media presence and professional networking profiles ### Advanced Analysis Tools (4 tools) - `evaluate_tech_stack` - Compare candidate's skills against required technologies - `assess_leadership_experience` - Analyze leadership roles and achievements - `calculate_experience_years` - Calculate experience for specific technologies - `match_job_requirements` - Match candidate against specific job requirements ### Security and Debugging Tools (2 tools) - `verify_response_signature` - Verify digital signatures of MCP responses - `get_server_public_key` - Get server's public key for external verification ## Adding New Tools Tools are defined in the `init()` method of the `MyMCP` class in `src/index.ts`. **All tools automatically sign their responses**. Use the pattern: ```typescript this.server.tool("tool-name", { param: z.type() }, async (params) => { const data = { /* your response data */ }; const signedResponse = this.crypto.signResponse(data); return { content: [{ type: "text", text: JSON.stringify(signedResponse, null, 2) }] }; }); ``` **Signed Response Format:** ```json { "data": { /* original tool data */ }, "hash": "sha256_hash", "signature": "rsa_signature_base64", "timestamp": "2025-01-15T10:00:00Z", "publicKey": "-----BEGIN PUBLIC KEY-----...", "serverId": "cv-server-id", "version": "1.0" } ``` ## Candidate Data Structure The candidate data in `src/candidate-data.json` is structured as: - `personal` - Contact info and professional summary - `workExperience` - Array of work positions with achievements - `education` - Academic background - `certifications` - Professional certifications - `skills` - Technical, design, productivity, and soft skills - `languages` - Language proficiencies - `interests` - Personal interests and hobbies - `experienceYears` - Calculated experience by technology/area ## Configuration Files - `wrangler.jsonc` - Cloudflare Workers configuration with Durable Objects binding - `biome.json` - Code formatting and linting configuration (4-space indentation, 100 character line width) - `tsconfig.json` - TypeScript configuration for Workers runtime - `worker-configuration.d.ts` - Auto-generated Cloudflare Workers type definitions - `.env.local` - Local development environment variables (generated by `npm run setup-keys`) - `scripts/generate-keys.js` - Cryptographic key generator for development ## Testing the MCP Server Local development runs on `localhost:8787` with digital signature support. Test endpoints: - `/sse` - Server-Sent Events endpoint for MCP connections - `/mcp` - Standard MCP endpoint **Setup for local testing:** 1. Run `npm run setup-keys` to generate cryptographic keys 2. Start server with `npm run dev` 3. All responses will be digitally signed automatically Connect to the server from Claude Desktop using the mcp-remote proxy as described in the README. ## Usage Examples for Recruiters ### Basic Candidate Information (All Digitally Signed) ``` get_candidate_profile -> Returns signed profile with contact info get_work_experience -> Returns signed detailed work history get_technical_skills -> Returns signed categorized technical abilities ``` ### Advanced Analysis (All Digitally Signed) ``` evaluate_tech_stack(["React", "Node.js", "TypeScript"]) -> Signed tech compatibility score match_job_requirements("Frontend Developer", ["React", "JavaScript"], ["Next.js"]) -> Signed job fit analysis assess_leadership_experience -> Signed leadership evaluation ``` ### Search and Discovery (All Digitally Signed) ``` search_candidate_info("React") -> Signed search results for React calculate_experience_years("JavaScript") -> Signed JS experience timeline ``` ### Security and Verification ``` verify_response_signature(signedResponse) -> Verify authenticity of any response get_server_public_key -> Get public key for external verification ``` ## Testing The project includes comprehensive testing for all MCP tools: - **Test Files**: Located in `tests/` directory - `tests/run-tests.js` - Main test runner with comprehensive tool validation - `tests/mcp-tools.test.js` - Specific MCP tool functionality tests - `tests/crypto.test.js` - **Digital signature and cryptographic tests** - `tests/test-report.json` - Generated test results and coverage report - **Testing Features**: - All 17 MCP tools are tested for functionality - **Digital signature validation** for all responses - **Cryptographic security testing** (7 specific tests) - Parameter validation testing - Response format verification - Error handling validation - **Signature manipulation detection** - Performance benchmarking - **Test Coverage**: Complete coverage including digital signature system See `TESTING.md` for detailed testing documentation and results. ## Documentation Additional project documentation is available in the `docs/` folder: - `docs/cv-to-mcp-prompt-template.md` - Reusable template for CV→MCP projects - `docs/project-journey.md` - Complete development process documentation (updated with signature implementation) - `docs/README.md` - Documentation overview - `docs/proyecto_cv_dinamico.md` - Advanced CV system architecture with digital signatures - `TESTING.md` - Comprehensive testing documentation including cryptographic tests