youdotcom-mcp-server: Instructions file for Claude Code

You.com MCP Server Development Guide

This is a Model Context Protocol (MCP) server that provides web search capabilities through You.com's Search API.

Runtime and Package Management

Use Bun instead of Node.js (requires Bun >= 1.2.21):

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Bun automatically loads .env files, so don't use dotenv

Local Development Setup

Set up your environment file with your You.com API key:

echo "export YDC_API_KEY=<you-api-key>" > .env
source .env

Usage: Replace <you-api-key> with your actual API key:

echo "export YDC_API_KEY=your-actual-api-key-here" > .env
source .env

This creates a .env file with your API key and loads it into your shell session.

Development Commands

• bun run dev - Start MCP server in stdio mode for development
• bun run build - Build production bundle to dist/
• bun run test - Run test suite
• bun run test:coverage - Run tests with coverage report
• bun run check - Run Biome linting and formatting checks
• bun run check:write - Auto-fix linting and formatting issues

Code Quality with Biome

This project uses Biome for linting and formatting instead of ESLint/Prettier:

• Configuration: Uses single quotes, space indentation, and auto-import organization
• Key Rules: noUnusedVariables: error, useConst: error
• Style Preference: Use arrow functions instead of function declarations
• Commands: Use bun run check to verify code quality, bun run check:write to auto-fix

MCP Server Development

Tool Registration

Use Zod schemas for tool parameter validation:

server.registerTool(
  'tool-name',
  {
    title: 'Tool Title',
    description: 'Tool description',
    inputSchema: SomeZodSchema.shape,
    outputSchema: ResponseSchema.shape,
  },
  async (parameters) => {
    // Tool implementation
    return {
      content: [{ type: 'text', text: 'Result' }],
      structuredContent: responseData,
    };
  }
);