hr-mcp-server: Instructions file for Claude Code

HR-MCP-SERVER-2 Development Guide

Commands

• Build: npm run build (TypeScript compiler with Node16 module system)
• Run server: npm start (runs the built JavaScript)
• Run dev: npx ts-node-esm src/index.ts (runs TypeScript directly)
• View logs: cat mcp.log (server communication logs)

Code Style

• Formatting: Use Prettier with default config
• Types: TypeScript strict mode with proper typing
• Naming:
  • camelCase for variables/functions
  • PascalCase for classes
  • Descriptive names that reveal intent
• Error handling:
  • Return isError: true for error responses
  • Validate all inputs with appropriate error messages
  • Use consistent error response format
• Comments:
  • Add explanatory comments for complex logic
  • Comment each tool with its purpose and parameters
  • Use section headers to organize related code
• Functions:
  • Single responsibility principle
  • Extract complex logic into helper functions
  • Keep functions at a reasonable size

Project Structure

• /src: Source code (main server implementation)
  • index.ts: Main server implementation with tools and prompts
  • /data: Data models and employee database
• /build: Compiled JavaScript output

MCP Server Implementation

• Use the high-level McpServer class from @modelcontextprotocol/sdk/server/mcp.js
• Initialize with new McpServer({ name: "server-name", version: "1.0.0" })
• Define tools with the server.tool() method:

  server.tool(
    "tool_name",
    { param_name: z.string().describe("Parameter description") },
    async ({ param_name }) => {
      // Tool implementation
      return {
        content: [{ type: "text", text: "Result text" }],
        isError: false // Set to true for error responses
      };
    }
  )
  

• Define prompts with the server.prompt() method:

  server.prompt(
    "prompt_name",
    "Description of what this prompt provides",
    { param_name: z.string().describe("Parameter description") },
    async ({ param_name }) => {
      // Prompt implementation
      return {
        messages: [
          {
            role: "user",
            content: { type: "text", text: "Your prompt text" }
          }
        ]
      };
    }
  )
  

• Tool response format must be:

  {
    content: [{ type: "text", text: string }],
    isError: boolean
  }
  

• Connect with stdio transport for Claude Desktop:

  const transport = new StdioServerTransport();
  server.connect(transport);
  

• Use centralized logging utility for consistent JSON-RPC format:

  // Define logging utility
  const logMessage = (message: string): void => {
    console.info(JSON.stringify({
      jsonrpc: "2.0",
      method: "log",
      params: { message }
    }));
  };
  
  // Use throughout code
  logMessage("Your log message here");