@youdotcom-oss/mcp 1.3.2 → 1.3.4

package/AGENTS.md

@@ -13,6 +13,7 @@ A Model Context Protocol (MCP) server that provides web search, AI agent, and co
 > **Note for end users**: If you want to use this MCP server (not develop or contribute), see [README.md](./README.md) for setup instructions, getting started guides, and usage examples.
 
 **This guide (AGENTS.md) is for developers, contributors, and AI coding agents** who want to:
+
 - Set up a local development environment
 - Understand the codebase architecture
 - Contribute code or bug fixes
@@ -24,11 +25,11 @@ A Model Context Protocol (MCP) server that provides web search, AI agent, and co
 ## Tech Stack
 
 - **Runtime**: Bun >= 1.2.21 (not Node.js)
-- **Framework**: Model Context Protocol SDK v1.22.0
+- **Framework**: Model Context Protocol SDK v1.24.0
 - **HTTP Server**: Hono v4.10.6 with @hono/mcp for HTTP transport (SSE protocol support)
 - **Validation**: Zod 3.25.76 for schema validation
 - **Testing**: Bun test (built-in test runner)
-- **Code Quality**: Biome 2.3.6 (linter + formatter)
+- **Code Quality**: Biome 2.3.7 (linter + formatter)
 - **Type Checking**: TypeScript 5.9.3
 - **Git Hooks**: lint-staged 16.2.7
 
@@ -48,17 +49,20 @@ bun install                    # Install dependencies
 bun run dev                    # Start stdio server
 bun start                      # Start HTTP server on port 4000
 bun test                       # Run tests
+bun test:coverage              # Run tests with coverage report
+bun test:watch                 # Run tests in watch mode
 bun run check                  # Run all checks (biome + types + package format)
 bun run check:write            # Auto-fix all issues
 ```
 
 ## Code Style
 
-This project uses [Biome](https://biomejs.dev/) for automated code formatting and linting. Most style rules are enforced automatically via git hooks (see `biome.json:55`).
+This project uses [Biome](https://biomejs.dev/) for automated code formatting and linting. Most style rules are enforced automatically via git hooks.
 
 ### Manual Adherence Required
 
 **Arrow Functions**: Always use arrow functions for declarations (not enforced by Biome)
+
 ```ts
 // ✅ Preferred
 export const fetchData = async (params: Params) => { ... };
@@ -68,6 +72,7 @@ export async function fetchData(params: Params) { ... }
 ```
 
 **No Unused Exports**: All exports must be actively used (Biome detects unused variables/imports, but NOT unused exports)
+
 ```bash
 # Before adding exports, verify usage:
 grep -r "ExportName" src/
@@ -76,36 +81,45 @@ grep -r "ExportName" src/
 ### MCP-Specific Patterns
 
 **Schema Design**: Always use Zod for input/output validation
+
 ```ts
 export const MyToolInputSchema = z.object({
-  query: z.string().min(1).describe('Search query'),
-  limit: z.number().optional().describe('Max results'),
+  query: z.string().min(1).describe("Search query"),
+  limit: z.number().optional().describe("Max results"),
 });
 ```
 
 **Error Handling**: Always use try/catch with typed error handling
+
 ```ts
 try {
   const response = await apiCall();
   return formatResponse(response);
 } catch (err: unknown) {
   const errorMessage = err instanceof Error ? err.message : String(err);
-  await logger({ level: 'error', data: `API call failed: ${errorMessage}` });
-  return { content: [{ type: 'text', text: `Error: ${errorMessage}` }], isError: true };
+  await logger({ level: "error", data: `API call failed: ${errorMessage}` });
+  return {
+    content: [{ type: "text", text: `Error: ${errorMessage}` }],
+    isError: true,
+  };
 }
 ```
 
 **Logging**: Use `getLogger(mcp)` helper, never console.log
+
 ```ts
+import { getLogger } from "../shared/get-logger.ts";
+
 const logger = getLogger(mcp);
-await logger({ level: 'info', data: `Operation successful: ${result}` });
-await logger({ level: 'error', data: `Operation failed: ${errorMessage}` });
+await logger({ level: "info", data: `Operation successful: ${result}` });
+await logger({ level: "error", data: `Operation failed: ${errorMessage}` });
 ```
 
 **Response Format**: Return both `content` and `structuredContent`
+
 ```ts
 return {
-  content: [{ type: 'text', text: formattedText }],
+  content: [{ type: "text", text: formattedText }],
   structuredContent: responseData,
 };
 ```
@@ -153,6 +167,7 @@ bun run format:package           # Format package.json only
 ## Contributing
 
 For detailed contribution guidelines, including:
+
 - Bug reporting
 - Feature requests
 - Pull request workflow
@@ -166,22 +181,22 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md)
 ### Tool Registration
 
 Use Zod schemas for tool parameter validation. See examples:
-- Search tool: `src/search/register-search-tool.ts:7-47`
-- Express tool: `src/express/register-express-tool.ts:7-35`
-- Contents tool: `src/contents/register-contents-tool.ts:7-45`
+
+- Search tool: `src/search/register-search-tool.ts:7-86`
+- Express tool: `src/express/register-express-tool.ts:7-66`
+- Contents tool: `src/contents/register-contents-tool.ts:7-89`
 
 ### Error Handling
 
-Always use try/catch with typed error handling (`err: unknown`). See `src/search/search.utils.ts:90-105` for standard pattern.
+Always use try/catch with typed error handling (`err: unknown`). See tool registration files for standard pattern.
 
 ### Logging
 
-Use `getLogger(mcp)` helper, never console.log. See `src/shared/shared.utils.ts:35-40` for implementation.
+Use `getLogger(mcp)` helper, never console.log. See `src/shared/get-logger.ts:8-11` for implementation.
 
 ### Error Reporting
 
-Include mailto links in error logs using `generateErrorReportLink()` helper (`src/shared/shared.utils.ts:75-100`). This creates one-click error reporting with full diagnostic context.
-
+Include mailto links in error logs using `generateErrorReportLink()` helper (`src/shared/generate-error-report-link.ts:6-37`). This creates one-click error reporting with full diagnostic context.
 
 ## Testing
 
@@ -192,6 +207,7 @@ Include mailto links in error logs using `generateErrorReportLink()` helper (`sr
 - **Coverage Target**: >80% for core utilities
 
 For test patterns, see:
+
 - Unit tests: `src/search/tests/search.utils.spec.ts`
 - Integration tests: `src/tests/tool.spec.ts`
 
@@ -200,30 +216,35 @@ For test patterns, see:
 **IMPORTANT: Avoid patterns that silently skip assertions** - they hide failures.
 
 ❌ **Early Returns** - Silently exits test, skips remaining assertions
+
 ```ts
 if (!item) return; // Bad: test passes even if item is undefined
 ```
 
 ❌ **Redundant Conditionals** - Asserts defined, then conditionally checks type
+
 ```ts
 expect(item?.markdown).toBeDefined();
 if (item?.markdown) {
-  expect(typeof item.markdown).toBe('string'); // Redundant!
+  expect(typeof item.markdown).toBe("string"); // Redundant!
 }
 ```
 
 ✅ **Let tests fail naturally** - Use optional chaining and direct assertions:
+
 ```ts
 expect(item).toBeDefined();
-expect(item).toHaveProperty('url'); // Fails with clear error if undefined
+expect(item).toHaveProperty("url"); // Fails with clear error if undefined
 ```
 
 ### Running Tests
 
 ```bash
-bun test                    # All tests
-bun test --coverage         # With coverage report
-bun test src/search/tests/  # Specific directory
+bun test                       # All tests
+bun test:coverage              # With coverage report
+bun test:watch                 # Run tests in watch mode
+bun test:coverage:watch        # Coverage with watch mode
+bun test src/search/tests/     # Specific directory
 ```
 
 Requires `YDC_API_KEY` environment variable for API tests.
@@ -237,6 +258,7 @@ Requires `YDC_API_KEY` environment variable for API tests.
 **Symptom**: Error message "YDC_API_KEY environment variable is required"
 
 **Solution**:
+
 ```bash
 # Set up .env file
 echo "export YDC_API_KEY=your-actual-api-key-here" > .env
@@ -254,6 +276,7 @@ echo $YDC_API_KEY
 **Symptom**: `bun run build` fails with TypeScript errors
 
 **Solution**:
+
 ```bash
 # Check TypeScript errors
 bun run check:types
@@ -271,6 +294,7 @@ bun run build
 **Symptom**: Tests fail with 429 (Too Many Requests) errors
 
 **Solution**:
+
 - Wait a few minutes before re-running tests
 - Run specific test suites instead of all tests at once
 - Use `bun test --bail` to stop after first failure
@@ -281,6 +305,7 @@ bun run build
 **Symptom**: Docker build fails with permission errors
 
 **Solution**:
+
 ```bash
 # Ensure Docker daemon is running
 docker info
@@ -297,6 +322,7 @@ groups $USER
 **Symptom**: Pre-commit hook fails or `bun run check` shows errors
 
 **Solution**:
+
 ```bash
 # Auto-fix most issues
 bun run check:write
@@ -318,6 +344,7 @@ bun run lint:fix
 **Symptom**: "Cannot find module" errors in TypeScript
 
 **Solution**:
+
 - Always use `.js` extensions in imports (even for `.ts` files)
 - Check that the file exists at the specified path
 - Use relative paths correctly (`./` for same directory, `../` for parent)
@@ -328,11 +355,13 @@ bun run lint:fix
 **Symptom**: MCP client can't connect to server
 
 **Solution for Stdio mode**:
+
 - Verify the path to `stdio.ts` or `stdio.js` is correct and absolute
 - Check that Bun is installed and in PATH
 - Test manually: `bun src/stdio.ts`
 
 **Solution for HTTP mode**:
+
 - Verify server is running: `curl http://localhost:4000/mcp-health`
 - Check port isn't in use: `lsof -i :4000` (macOS/Linux)
 - Verify Bearer token matches your API key
@@ -363,13 +392,13 @@ const validatedResponse = ResponseSchema.parse(jsonResponse);
 
 // Handle specific status codes
 if (response.status === 401) {
-  throw new Error('Invalid or expired API key');
+  throw new Error("Invalid or expired API key");
 }
 if (response.status === 403) {
-  throw new Error('API key lacks permissions for this endpoint');
+  throw new Error("API key lacks permissions for this endpoint");
 }
 if (response.status === 429) {
-  throw new Error('Rate limit exceeded');
+  throw new Error("Rate limit exceeded");
 }
 ```
 
@@ -412,7 +441,7 @@ Content extraction from web pages
 graph TD
     Clients["MCP Clients
     (Claude Desktop, Claude Code, Custom Clients)"]
-    
+
     Clients -->|"Stdio (Local)"| Stdio["src/stdio.ts
     - Process I/O
     - JSON-RPC"]
@@ -420,14 +449,14 @@ graph TD
     - /mcp
     - /mcp-health
     - Bearer Auth"]
-    
+
     Stdio --> Server["src/get-mcp-server.ts
     MCP Server Factory
     - registerTool()
     - Tool Handlers
     - Logging"]
     HTTP --> Server
-    
+
     Server --> Search["you-search
     - Validation
     - Query Build
@@ -440,7 +469,7 @@ graph TD
     - Validation
     - Multi-URL
     - Formatting"]
-    
+
     Search -->|X-API-Key| APIs["You.com APIs
     - Search API (ydc-index.io)
     - Agent API (api.you.com)
@@ -452,6 +481,7 @@ graph TD
 ### Request Flow
 
 **Stdio Transport (Local Development)**:
+
 1. MCP Client sends JSON-RPC request via stdin
 2. `stdio.ts` receives and parses request
 3. Calls MCP Server with tool name + parameters
@@ -461,6 +491,7 @@ graph TD
 7. JSON-RPC response sent via stdout
 
 **HTTP Transport (Remote Deployment)**:
+
 1. MCP Client connects via SSE to `/mcp`
 2. Client sends tool request over SSE connection
 3. `http.ts` authenticates Bearer token
@@ -521,11 +552,24 @@ graph TD
 
 ### Shared Utilities
 
-- `src/shared/shared.utils.ts` - Cross-tool utilities
-  - `useGetClientVersion(mcp)` - Returns a `getUserAgent` function that creates User-Agent strings with MCP client version info
+- `src/shared/use-client-version.ts` - User-Agent generation with MCP client version info
+  - `useGetClientVersion(mcp)` - Returns a `getUserAgent` function for creating User-Agent strings
+- `src/shared/get-logger.ts` - MCP server logging
   - `getLogger(mcp)` - Returns a logging function for MCP server notifications
+- `src/shared/check-response-for-errors.ts` - API response validation
   - `checkResponseForErrors()` - Validates API responses for error fields
-  - `generateErrorReportLink()` - Creates mailto links for error reporting
+- `src/shared/generate-error-report-link.ts` - Error reporting utilities
+  - `generateErrorReportLink()` - Creates mailto links for one-click error reporting
+- `src/shared/format-search-results-text.ts` - Search result formatting
+  - `formatSearchResultsText()` - Formats search results for text display
+
+### Library Export
+
+- `src/main.ts` - Public API export file for library consumers
+  - Exports all schemas from contents, express, and search tools
+  - Exports utility functions from contents, express, and search
+  - Exports shared utilities (checkResponseForErrors, formatSearchResultsText)
+  - Used when consuming this package as a library (not as MCP server)
 
 ### Integration Tests
 
@@ -534,35 +578,134 @@ graph TD
 
 ## Deployment
 
-### Quick Start
+This section covers local development setup, self-hosting options, and production deployment strategies.
+
+### Local development setup
+
+**Prerequisites:**
+
+- Bun >= 1.2.21 installed
+- You.com API key from [you.com/platform/api-keys](https://you.com/platform/api-keys)
+
+**Quick start:**
 
 ```bash
-# Local development
-git clone <repository-url>
-cd you-mcp-server
+# Clone repository
+git clone https://github.com/youdotcom-oss/youdotcom-mcp-server.git
+cd youdotcom-mcp-server
+
+# Install dependencies
 bun install
-echo "export YDC_API_KEY=your-key" > .env
+
+# Set up environment
+echo "export YDC_API_KEY=your-actual-api-key-here" > .env
 source .env
-bun run dev  # Stdio mode
 
-# HTTP server
-bun start    # Port 4000
+# Start development server (STDIO mode)
+bun run dev
+
+# Or start HTTP server on port 4000
+bun start
+```
+
+**Verify setup:**
+
+```bash
+# Test STDIO mode
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | bun src/stdio.ts
+
+# Test HTTP mode (in separate terminal)
+curl http://localhost:4000/mcp-health
+```
+
+### Self-hosting with Docker
+
+**Build and run:**
 
-# Docker
+```bash
+# Build Docker image
 docker build -t youdotcom-mcp-server .
-docker run -d -p 4000:4000 youdotcom-mcp-server
+
+# Run container with API key
+docker run -d \
+  -p 4000:4000 \
+  --name youdotcom-mcp \
+  -e YDC_API_KEY=your-actual-api-key-here \
+  youdotcom-mcp-server
+
+# Check health
+curl http://localhost:4000/mcp-health
 ```
 
-### Deployment Modes
+**Docker Compose:**
+
+```yaml
+version: "3.8"
+services:
+  youdotcom-mcp:
+    build: .
+    ports:
+      - "4000:4000"
+    environment:
+      - YDC_API_KEY=${YDC_API_KEY}
+    restart: unless-stopped
+```
+
+### Deployment modes
 
-| Mode | Use Case | Command |
-|------|----------|---------|
-| **Stdio Dev** | Local development | `bun run dev` |
-| **Stdio Prod** | MCP client integration | `./bin/stdio.js` |
-| **HTTP** | Web apps, remote clients | `bun start` |
-| **Docker** | Containerized deployment | `docker run ...` |
+| Mode           | Use Case                             | Transport | Command                         |
+| -------------- | ------------------------------------ | --------- | ------------------------------- |
+| **STDIO Dev**  | Local development and testing        | STDIO     | `bun run dev`                   |
+| **STDIO Prod** | MCP client integration (local)       | STDIO     | `./bin/stdio.js`                |
+| **HTTP Dev**   | Local HTTP server testing            | HTTP/SSE  | `bun start`                     |
+| **HTTP Prod**  | Remote clients, web apps, production | HTTP/SSE  | `bun run build && bun bin/http` |
+| **Docker**     | Containerized deployment             | HTTP/SSE  | `docker run ...`                |
 
-For detailed deployment instructions, Docker configuration, and MCP client setup, see README.md.
+### Production deployment
+
+**Building for production:**
+
+```bash
+# Build optimized STDIO bundle
+bun run build
+
+# Outputs:
+# - bin/stdio.js (compiled STDIO transport)
+# Note: bin/http is an executable script, not compiled
+```
+
+**Running in production:**
+
+```bash
+# Set API key
+export YDC_API_KEY=your-actual-api-key-here
+
+# STDIO mode (for MCP clients)
+node bin/stdio.js
+
+# HTTP mode (for remote access)
+PORT=4000 bun bin/http
+```
+
+**Environment variables:**
+
+| Variable      | Required | Default | Description                       |
+| ------------- | -------- | ------- | --------------------------------- |
+| `YDC_API_KEY` | Yes      | -       | You.com API key                   |
+| `PORT`        | No       | 4000    | HTTP server port (HTTP mode only) |
+
+**Production considerations:**
+
+- **Security**: Never expose STDIO mode to external networks
+- **HTTP mode**: Use reverse proxy (nginx, Caddy) with HTTPS in production
+- **Rate limiting**: Consider implementing rate limiting for HTTP endpoints
+- **Monitoring**: Set up health check monitoring on `/mcp-health`
+- **Logging**: MCP server logs to stderr; configure log aggregation as needed
+- **API key rotation**: Restart server after rotating API keys
+
+### MCP client configuration
+
+For connecting MCP clients to your self-hosted server, see the "Adding to your MCP client" section in [README.md](./README.md).
 
 For complete API reference documentation including parameters, response formats, and examples, see [API.md](./docs/API.md).
 
@@ -577,10 +720,11 @@ bun test         # Built-in test runner
 ```
 
 **Import Extensions** (enforced by Biome):
+
 - Local files: `.ts` extension
 - NPM packages: `.js` extension
 - JSON files: `.json` with import assertion
 
 See `src/contents/register-contents-tool.ts:1-5` for import examples.
 
-**Build**: See `scripts/build.ts` for Bun.build configuration.
+**Build**: Build configuration is defined in `package.json` scripts. The `bun run build` command compiles `src/stdio.ts` to `bin/stdio.js` for production use.