@youdotcom-oss/mcp 1.3.3 → 1.3.5-next.5

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,7 +25,7 @@ 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)
@@ -61,6 +62,7 @@ This project uses [Biome](https://biomejs.dev/) for automated code formatting an
 ### Manual Adherence Required
 
 **Arrow Functions**: Always use arrow functions for declarations (not enforced by Biome)
+
 ```ts
 // ✅ Preferred
 export const fetchData = async (params: Params) => { ... };
@@ -70,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/
@@ -78,38 +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';
+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,
 };
 ```
@@ -157,6 +167,7 @@ bun run format:package           # Format package.json only
 ## Contributing
 
 For detailed contribution guidelines, including:
+
 - Bug reporting
 - Feature requests
 - Pull request workflow
@@ -165,11 +176,72 @@ For detailed contribution guidelines, including:
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md)
 
+## Publishing
+
+### Release Process
+
+This package is published to npm via the `.github/workflows/publish-mcp.yml` workflow in the monorepo root.
+
+**Workflow Actions**:
+1. Updates version in `packages/mcp/package.json`
+2. Scans all workspace packages for dependencies on `@youdotcom-oss/mcp`
+3. Updates dependent packages with exact version (e.g., "1.4.0")
+4. Commits all version updates together
+5. Creates GitHub release in private repo
+6. Syncs to OSS repo via git subtree split
+7. Creates GitHub release in OSS repo
+8. Publishes to npm
+
+**Version Format**: Exact versions only (no `^` or `~` prefixes)
+
+```json
+{
+  "dependencies": {
+    "@youdotcom-oss/mcp": "1.3.4"
+  }
+}
+```
+
+**IMPORTANT**: If you add dependencies on other workspace packages, use exact version numbers. The publish workflow will automatically keep them in sync when new versions are released.
+
+### Version Format Convention
+
+This package follows standard Git tagging conventions:
+
+- **Git tags**: `v{version}` (e.g., `v1.3.4`, `v1.4.0-next.1`)
+- **GitHub releases**: `v{version}` (e.g., `Release v1.3.4`)
+- **package.json**: `{version}` (no "v" prefix, e.g., `1.3.4`)
+- **npm package**: `{version}` (no "v" prefix, e.g., `@youdotcom-oss/mcp@1.3.4`)
+
+**When triggering the publish workflow:**
+1. Go to: Actions → Publish mcp-server Release → Run workflow
+2. Enter version WITHOUT "v" prefix: `1.3.4` (not `v1.3.4`)
+3. The workflow automatically adds "v" for Git tags
+4. Validation checks prevent common mistakes
+
+**Example:**
+```bash
+# Workflow input
+Version: 1.3.4
+
+# Produces:
+# - Git tag: v1.3.4
+# - package.json: "version": "1.3.4"
+# - npm: @youdotcom-oss/mcp@1.3.4
+# - Release: https://github.com/.../releases/tag/v1.3.4
+```
+
+**Validation checks in workflow:**
+- Rejects input with "v" prefix
+- Verifies package.json matches release version
+- Ensures no "v" prefix in package.json
+
 ## MCP Server Patterns
 
 ### Tool Registration
 
 Use Zod schemas for tool parameter validation. See examples:
+
 - 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`
@@ -186,7 +258,6 @@ Use `getLogger(mcp)` helper, never console.log. See `src/shared/get-logger.ts:8-
 
 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
 
 ### Test Organization
@@ -196,6 +267,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`
 
@@ -204,22 +276,25 @@ 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
@@ -243,6 +318,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
@@ -260,6 +336,7 @@ echo $YDC_API_KEY
 **Symptom**: `bun run build` fails with TypeScript errors
 
 **Solution**:
+
 ```bash
 # Check TypeScript errors
 bun run check:types
@@ -277,32 +354,19 @@ 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
 - Check your API key rate limits at [api.you.com](https://api.you.com)
 
-#### Docker Permission Issues
-
-**Symptom**: Docker build fails with permission errors
-
-**Solution**:
-```bash
-# Ensure Docker daemon is running
-docker info
-
-# Build with sudo if needed (Linux)
-sudo docker build -t youdotcom-mcp-server .
-
-# Check Docker group membership (Linux)
-groups $USER
-```
 
 #### Biome/TypeScript Errors
 
 **Symptom**: Pre-commit hook fails or `bun run check` shows errors
 
 **Solution**:
+
 ```bash
 # Auto-fix most issues
 bun run check:write
@@ -324,6 +388,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)
@@ -334,11 +399,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
@@ -369,13 +436,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");
 }
 ```
 
@@ -418,7 +485,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"]
@@ -426,14 +493,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
@@ -446,7 +513,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)
@@ -458,6 +525,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
@@ -467,6 +535,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
@@ -558,6 +627,7 @@ This section covers local development setup, self-hosting options, and productio
 ### 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)
 
@@ -565,8 +635,8 @@ This section covers local development setup, self-hosting options, and productio
 
 ```bash
 # Clone repository
-git clone https://github.com/youdotcom-oss/youdotcom-mcp-server.git
-cd youdotcom-mcp-server
+git clone https://github.com/youdotcom-oss/mcp-server.git
+cd mcp-server
 
 # Install dependencies
 bun install
@@ -583,6 +653,7 @@ bun start
 ```
 
 **Verify setup:**
+
 ```bash
 # Test STDIO mode
 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | bun src/stdio.ts
@@ -591,48 +662,18 @@ echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | bun src/stdio.ts
 curl http://localhost:4000/mcp-health
 ```
 
-### Self-hosting with Docker
+### Self-hosting
 
-**Build and run:**
-
-```bash
-# Build Docker image
-docker build -t 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
-```
-
-**Docker Compose:**
-
-```yaml
-version: '3.8'
-services:
-  youdotcom-mcp:
-    build: .
-    ports:
-      - "4000:4000"
-    environment:
-      - YDC_API_KEY=${YDC_API_KEY}
-    restart: unless-stopped
-```
+This package supports self-hosting in STDIO or HTTP modes (see deployment modes below).
 
 ### Deployment modes
 
-| 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 ...` |
+| 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` |
 
 ### Production deployment
 
@@ -662,10 +703,10 @@ 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) |
+| Variable      | Required | Default | Description                       |
+| ------------- | -------- | ------- | --------------------------------- |
+| `YDC_API_KEY` | Yes      | -       | You.com API key                   |
+| `PORT`        | No       | 4000    | HTTP server port (HTTP mode only) |
 
 **Production considerations:**
 
@@ -693,6 +734,7 @@ 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

package/README.md

@@ -277,7 +277,7 @@ If you encounter a problem, you can report it via email or GitHub:
 
 **Web support:** [You.com Support](https://you.com/support/contact-us)
 
-**GitHub Issues:** [Report bugs and feature requests](https://github.com/youdotcom-oss/youdotcom-mcp-server/issues)
+**GitHub Issues:** [Report bugs and feature requests](https://github.com/youdotcom-oss/mcp-server/issues)
 
 **Tip:** When errors occur, check your MCP client logs - they include a pre-filled mailto link with error details for easy reporting.