@youdotcom-oss/mcp 1.3.1 → 1.3.3

package/README.md

@@ -1,45 +1,45 @@
 # You.com MCP Server
 
-A Model Context Protocol (MCP) server that provides web search, AI-powered answers, and content extraction using You.com APIs. Built with Bun runtime for optimal performance and supports multiple transport protocols for compatibility with different MCP clients.
+The You.com MCP Server gives your AI agents **real-time access to the latest web information** through the [Model Context Protocol](https://modelcontextprotocol.io/). Search current content, get up-to-date answers, and extract live web pages—whether in your IDE or deployed agentic workflows. Built on MCP to **work everywhere your agents do**—one integration, unlimited compatibility across IDEs, frameworks, and production systems. 
 
 ## Features
 
-- **Web and News Search**: Comprehensive search using You.com's unified Search API with advanced search operators
-- **AI-Powered Express Agent**: Fast responses with optional real-time web search integration
-- **Content Extraction**: Extract and retrieve full content from web pages in markdown or HTML format
-- **Multiple Transport Protocols**: Stdio and Streamable HTTP support
+- **Web and news search**: Comprehensive search using You.com's unified Search API with advanced search operators
+- **AI-powered Express Agent**: Fast responses with optional real-time web search integration
+- **Content extraction**: Extract and retrieve full content from web pages in markdown or HTML format
+- **Multiple transport protocols**: STDIO and Streamable HTTP support
 - **Bearer Token Authentication**: Secure API access in HTTP mode
-- **TypeScript Support**: Full type safety with Zod schemas
-- **Advanced Search Parameters**: Site filtering, file type filtering, language filtering, exact terms, and exclude terms
+- **TypeScript support**: Full type safety with Zod schemas
+- **Advanced search parameters**: Site filtering, file type filtering, language filtering, exact terms, and exclude terms
 
-## Getting Started
+## Getting started
 
 Get up and running with the You.com MCP Server in 4 quick steps:
 
-### 1. Get Your API Key
+### 1. Get your API key
 
 Visit [you.com/platform/api-keys](https://you.com/platform/api-keys) to get your You.com API key. Keep this key secure - you'll need it for configuration.
 
-### 2. Choose Your Setup
+### 2. Choose your setup
 
-**Remote Server (Recommended)** - No installation, always up-to-date, just add the URL and API key
+**Remote server (recommended)** - No installation, always up-to-date, just add the URL and API key
 - Use `https://api.you.com/mcp` with HTTP transport
 - Authentication via `Authorization: Bearer <your-key>` header
 
-**NPM Package** - Runs locally on your machine
-- Use `npx @youdotcom-oss/mcp` with stdio transport
+**NPM package** - Runs locally on your machine
+- Use `npx @youdotcom-oss/mcp` with STDIO transport
 - Authentication via `YDC_API_KEY` environment variable
 - Requires Bun or Node.js
 
-### 3. Configure Your Client
+### 3. Configure your client
 
 Choose your MCP client from the [detailed setup guides](#adding-to-your-mcp-client) below. Most clients use this basic structure:
 
-**Remote Server:**
+**Remote server (recommended):**
 ```json
 {
   "mcpServers": {
-    "ydc-search": {
+    "ydc-server": {
       "type": "http",
       "url": "https://api.you.com/mcp",
       "headers": { "Authorization": "Bearer <you-api-key>" }
@@ -48,11 +48,11 @@ Choose your MCP client from the [detailed setup guides](#adding-to-your-mcp-clie
 }
 ```
 
-**NPM Package:**
+**NPM package:**
 ```json
 {
   "mcpServers": {
-    "ydc-search": {
+    "ydc-server": {
       "command": "npx",
       "args": ["@youdotcom-oss/mcp"],
       "env": { "YDC_API_KEY": "<you-api-key>" }
@@ -61,7 +61,13 @@ Choose your MCP client from the [detailed setup guides](#adding-to-your-mcp-clie
 }
 ```
 
-### 4. Test Your Setup
+**Configuration notes:**
+- Remote server recommended for most users (no installation, always up-to-date)
+- NPM package for local usage or self-hosting scenarios
+- HTTP transport for remote connections; STDIO transport for local packages
+- API key always required (header for HTTP, environment variable for STDIO)
+
+### 4. Test your setup
 
 Ask your AI agent a simple query to verify everything works:
 - "Search the web for the latest news about artificial intelligence"
@@ -74,322 +80,104 @@ Your agent will automatically use the appropriate tool based on your natural lan
 
 Detailed configuration instructions for specific MCP clients. See [Getting Started](#getting-started) above for a quick overview.
 
-### Standard Configuration Templates
-
-**Configuration Notes:**
-- Remote server recommended for most users (no installation, always up-to-date)
-- NPM package for local usage or self-hosting scenarios
-- HTTP transport for remote connections; stdio transport for local packages
-- API key always required (header for HTTP, environment variable for stdio)
-
-**Remote Server (Recommended):**
-```json
-{
-  "mcpServers": {
-    "ydc-search": {
-      "type": "http",
-      "url": "https://api.you.com/mcp",
-      "headers": {
-        "Authorization": "Bearer <you-api-key>"
-      }
-    }
-  }
-}
-```
-
-**Local NPM Package:**
-```json
-{
-  "mcpServers": {
-    "ydc-search": {
-      "command": "npx",
-      "args": ["@youdotcom-oss/mcp"],
-      "env": {
-        "YDC_API_KEY": "<you-api-key>"
-      }
-    }
-  }
-}
-```
-
 <details>
 <summary><strong>Claude Code</strong></summary>
 
-**Quick Setup:**
+Use the Claude Code CLI to add the You.com MCP server:
+
+**Quick setup:**
 ```bash
-# Add using Claude Code CLI (if available)
-claude mcp add ydc-search npx @youdotcom-oss/mcp
+claude mcp add --transport http ydc-server https://api.you.com/mcp --header "Authorization: Bearer <your-api-key>"
 ```
 
-**Manual Setup:**
-1. Follow the [Claude Code setup guide](https://docs.anthropic.com/en/docs/claude-code/setup)
-2. Create or update `.mcp.json` in your workspace root using the standard configuration template above
-3. For remote server: add `"type": "http"` to the configuration
-4. For local package: add `"type": "stdio"` to the configuration
+For setup, follow the MCP installation [guide](https://code.claude.com/docs/en/mcp).
 
 </details>
 
 <details>
 <summary><strong>Claude Desktop</strong></summary>
 
-**Setup:**
-Use the standard configuration template above in your Claude Desktop MCP configuration.
-
-**Installation:**
-Follow the [Claude Desktop MCP guide](https://docs.anthropic.com/en/docs/build-with-claude/computer-use) for setup.
-
-[Download Claude Desktop](https://claude.ai/download)
+For setup, follow the MCP installation [guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
 
 </details>
 
 <details>
 <summary><strong>Codex</strong></summary>
 
-**Setup:**
-Edit `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.ydc-search]
-command = "npx"
-args = ["@youdotcom-oss/mcp"]
-
-[mcp_servers.ydc-search.env]
-YDC_API_KEY = "<you-api-key>"
-```
-
-[Download Codex](https://github.com/openai/codex)
+For setup, follow the MCP installation [guide](https://github.com/openai/codex/blob/main/docs/config.md#streamable-http).
 
 </details>
 
 <details>
 <summary><strong>Cursor IDE</strong></summary>
 
-**GUI Setup (Easiest):**
-1. Go to Cursor Settings > Features > MCP
-2. Click "+ Add New MCP Server"
-3. For remote: Select "Streamable HTTP" transport, URL: `https://api.you.com/mcp`
-4. For local: Select "stdio" transport, Command: `npx`, Args: `@youdotcom-oss/mcp`
-
-**Manual Setup:**
-Create `.cursor/mcp.json` in your project directory or `~/.cursor/mcp.json` globally using the standard configuration template above.
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ydc-server&config=eyJ1cmwiOiJodHRwczovL2FwaS55b3UuY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8eW91LWFwaS1rZXk%2BIn19)
 
-**Note:** Remove the `"type"` field from the remote server configuration for Cursor.
+For setup, follow the MCP installation [guide](https://cursor.com/docs/context/mcp#installing-mcp-servers); use the configuration template above ***without type field***.
 
-[Documentation](https://docs.cursor.com/en/context/mcp) | [Download Cursor](https://cursor.com)
+**Note:** To avoid conflicts, go to Settings > Agents tab and turn off Cursor's built-in web search tool.
 
 </details>
 
 <details>
 <summary><strong>Gemini CLI</strong></summary>
 
-**Setup:**
-Use the standard configuration template above in your Gemini CLI MCP server configuration.
-
-**Installation:**
-1. Install [Gemini CLI](https://google-gemini.github.io/gemini-cli/)
-2. Follow the [MCP server setup guide](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html)
-
-[Documentation](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) | [Download Gemini CLI](https://google-gemini.github.io/gemini-cli/)
-
-</details>
-
-<details>
-<summary><strong>Goose</strong></summary>
-
-**Quick Setup:**
-Go to "Advanced settings" → "Extensions" → "Add custom extension"
-
-**Manual Setup:**
-Use the standard configuration template above in your Goose extensions configuration.
-
-[Installation Guide](https://block.github.io/goose/docs/getting-started/installation) | [Download Goose](https://block.github.io/goose/)
+For setup, follow the MCP installation [guide](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html#how-to-set-up-your-mcp-server); use the configuration template above.
 
 </details>
 
 <details>
 <summary><strong>JetBrains IDEs</strong></summary>
 
-**Setup:**
-Configure in your IDE settings using the local NPM package configuration from the standard template above.
-
-**For Remote Server:**
-Use [mcp-remote](https://www.npmjs.com/package/mcp-remote) since JetBrains only supports stdio transport:
-```json
-{
-  "mcpServers": {
-    "ydc-search": {
-      "command": "npx",
-      "args": ["mcp-remote", "https://api.you.com/mcp", "--header", "Authorization: Bearer ${YDC_API_KEY}"],
-      "env": { "YDC_API_KEY": "<you-api-key>" }
-    }
-  }
-}
-```
+For setup, follow the MCP installation [guide](https://www.jetbrains.com/help/ai-assistant/mcp.html#connect-to-an-mcp-server); use the configuration template above.
 
 **Supported IDEs:** IntelliJ IDEA, PyCharm, WebStorm, etc. (requires AI Assistant enabled)
 
-[Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html)
-
 </details>
 
 <details>
 <summary><strong>LM Studio</strong></summary>
 
-**Setup:**
-Edit `mcp.json` in LM Studio settings using the standard configuration template above.
-
-**Installation:**
-Configure through program settings or edit configuration file manually.
-
-[Download LM Studio](https://lmstudio.ai/)
+For setup, follow the MCP installation [guide](https://lmstudio.ai/docs/app/mcp); use the configuration template above ***without type field***.
 
 </details>
 
 <details>
 <summary><strong>opencode</strong></summary>
 
-**Setup:**
-Edit `~/.config/opencode/opencode.json`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "ydc-search": {
-      "type": "local",
-      "command": ["npx", "@youdotcom-oss/mcp"],
-      "enabled": true,
-      "env": { "YDC_API_KEY": "<you-api-key>" }
-    }
-  }
-}
-```
-
-**For Remote Server:**
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "ydc-search": {
-      "type": "local",
-      "command": ["npx", "mcp-remote", "https://api.you.com/mcp", "--header", "Authorization: Bearer ${YDC_API_KEY}"],
-      "enabled": true,
-      "env": { "YDC_API_KEY": "<you-api-key>" }
-    }
-  }
-}
-```
-
-[Documentation](https://opencode.ai/docs)
-
-</details>
-
-<details>
-<summary><strong>Qodo Gen</strong></summary>
-
-**Setup:**
-1. Open Qodo Gen chat panel in VSCode or IntelliJ
-2. Click "Connect more tools" → "+ Add new MCP"
-3. Paste the standard config above
-4. Click Save
-
-[Documentation](https://docs.qodo.ai/qodo-documentation/qodo-gen)
+For setup, follow the MCP installation [guide](https://opencode.ai/docs/mcp-servers/#remote); use the configuration template above.
 
 </details>
 
 <details>
 <summary><strong>VS Code</strong></summary>
 
-**Quick Setup (Command Line):**
-```bash
-# Add MCP server
-code --add-mcp "{\"name\":\"ydc-search\",\"command\":\"npx\",\"args\":[\"@youdotcom-oss/mcp\"],\"env\":{\"YDC_API_KEY\":\"<you-api-key>\"}}"
-```
-
-**Manual Setup:**
-Create `mcp.json` file in your workspace (`.vscode/mcp.json`) or user profile using the standard configuration template above, but replace `"mcpServers"` with `"servers"`.
+Use the VS Code CLI to add the You.com MCP server:
 
-**Secure Setup with Input Prompts:**
-```json
-{
-  "inputs": [
-    {
-      "type": "promptString",
-      "id": "ydc-api-key",
-      "description": "You.com API Key",
-      "password": true
-    }
-  ],
-  "servers": {
-    "ydc-search": {
-      "command": "npx",
-      "args": ["@youdotcom-oss/mcp"],
-      "env": { "YDC_API_KEY": "${input:ydc-api-key}" }
-    }
-  }
-}
+**Quick setup (command line):**
+```bash
+code --add-mcp "{\"name\":\"ydc-server\",\"url\":\"https://api.you.com/mcp\",\"type\":\"http\",\"headers\":{\"Authorization\":\"Bearer <your-api-key>\"}}"
 ```
 
-**Requirements:** GitHub Copilot extension must be installed
-
-[Documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_commandline-configuration) | [Download VS Code](https://code.visualstudio.com/)
+For setup, follow the MCP installation [guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server); use the configuration template above.
 
 </details>
 
 <details>
 <summary><strong>Windsurf</strong></summary>
 
-**Setup:**
-Use the standard configuration template above.
-
-**Installation:**
-Follow MCP documentation for Windsurf-specific setup instructions.
-
-[Documentation](https://docs.windsurf.com/windsurf/cascade/mcp) | [Download Windsurf](https://docs.windsurf.com/windsurf/getting-started)
+For setup, follow the MCP installation [guide](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin).
 
 </details>
 
 <details>
 <summary><strong>Zed Editor</strong></summary>
 
-**Setup:**
-Add to your Zed `settings.json` using `"context_servers"` instead of `"mcpServers"`:
-
-```json
-{
-  "context_servers": {
-    "ydc-search": {
-      "source": "custom",
-      "command": "npx",
-      "args": ["@youdotcom-oss/mcp"],
-      "env": {
-        "YDC_API_KEY": "<you-api-key>"
-      }
-    }
-  }
-}
-```
-
-**For Remote Server:**
-Use [mcp-remote](https://www.npmjs.com/package/mcp-remote) to bridge HTTP to stdio:
-```json
-{
-  "context_servers": {
-    "ydc-search": {
-      "source": "custom",
-      "command": "npx",
-      "args": ["mcp-remote", "https://api.you.com/mcp", "--header", "Authorization: Bearer ${YDC_API_KEY}"],
-      "env": { "YDC_API_KEY": "<you-api-key>" }
-    }
-  }
-}
-```
-
-[Setup Instructions](https://zed.dev/docs/ai/mcp) | [Download Zed](https://zed.dev)
+For setup, follow the MCP installation [guide](https://zed.dev/docs/ai/mcp#as-custom-servers); use the configuration template above ***without type field***.
 
 </details>
 
-## Available Tools
+## Available tools
 
 This MCP server provides three tools that work seamlessly with your AI agent through natural language:
 
@@ -412,11 +200,11 @@ Extract full page content from URLs in markdown or HTML format. Useful for docum
 
 **Note**: Your MCP client automatically shows you all available parameters and their descriptions when you use these tools. Simply ask your AI agent in natural language what you want to do, and it will orchestrate the appropriate tool calls for you.
 
-## Use Cases & Examples
+## Use cases & examples
 
 Here are common scenarios showing when and how to use each tool with natural language queries:
 
-### Research & Information Gathering
+### Research & information gathering
 
 **Use you-search when:**
 - "Find recent research papers about quantum computing on arxiv.org"
@@ -430,7 +218,7 @@ Here are common scenarios showing when and how to use each tool with natural lan
 - "What happened in the tech industry today?" (with web search enabled)
 - "Summarize the main features of the latest Python release"
 
-### Content Extraction & Analysis
+### Content extraction & analysis
 
 **Use you-contents when:**
 - "Extract the content from this blog post: https://example.com/article"
@@ -438,29 +226,29 @@ Here are common scenarios showing when and how to use each tool with natural lan
 - "Pull the HTML content from this page preserving the layout"
 - "Batch extract content from these 5 documentation pages"
 
-### Combined Workflows
+### Combined workflows
 
 Your AI agent can combine multiple tools in a single conversation:
 1. **Research + Extract**: "Search for the best TypeScript tutorials, then extract the content from the top 3 results"
 2. **Question + Deep Dive**: "What is WebAssembly? Then search for real-world examples and extract code samples"
 3. **News + Analysis**: "Find recent articles about AI regulation, then summarize the key points"
 
-### Pro Tips
+### Pro tips
 
 - **Be specific**: Include domains, date ranges, or file types when searching
 - **Natural language**: You don't need to memorize parameters - just describe what you want
 - **Follow up**: Ask clarifying questions to refine results
 - **Combine tools**: Let your agent orchestrate multiple tool calls for complex workflows
 
-## Troubleshooting & Support
+## Troubleshooting & support
 
-### Common Issues
+### Common issues
 
 **Server not connecting:**
 - Verify your API key is correct and properly formatted
 - Check that your MCP client configuration matches the template for your setup (remote vs local)
 - For HTTP mode: Ensure the Authorization header includes "Bearer " prefix
-- For stdio mode: Verify the YDC_API_KEY environment variable is set
+- For STDIO mode: Verify the YDC_API_KEY environment variable is set
 
 **Tool not working:**
 - Check your MCP client logs for error messages
@@ -470,10 +258,10 @@ Your AI agent can combine multiple tools in a single conversation:
 
 **Authentication errors:**
 - Remote server uses Bearer token authentication in headers
-- Local stdio mode uses YDC_API_KEY environment variable
+- Local STDIO mode uses YDC_API_KEY environment variable
 - Make sure you're using the correct authentication method for your setup
 
-### Error Logs
+### Error logs
 
 Error messages and detailed logs appear in your MCP client's log output. Check your client's documentation for how to access logs:
 - Claude Code: Check terminal output or logs
@@ -481,78 +269,26 @@ Error messages and detailed logs appear in your MCP client's log output. Check y
 - Cursor: Check MCP server logs in settings
 - VS Code: View Output panel for MCP server logs
 
-### Report an Issue
+### Report an issue
 
 If you encounter a problem, you can report it via email or GitHub:
 
-**Email Support:** support@you.com
+**Email support:** support@you.com
 
-**Web Support:** [You.com Support](https://you.com/support/contact-us)
+**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)
 
 **Tip:** When errors occur, check your MCP client logs - they include a pre-filled mailto link with error details for easy reporting.
 
-## For Contributors
+## For contributors
 
 Interested in contributing to the You.com MCP Server? We'd love your help!
 
-**Note:** This section is for contributors and self-hosting only. Most users should use the remote server or NPM package from [Getting Started](#getting-started).
-
-### Development Setup
-
-For complete development setup instructions, code style guidelines, testing patterns, and contribution workflow, see [AGENTS.md](./AGENTS.md).
-
-The developer guide includes:
-- Local workspace setup with Bun runtime
-- Code style preferences and TypeScript guidelines
-- MCP-specific patterns and best practices
-- Testing strategy and examples
-- Git hooks and code quality tools
-- API integration details
-- Architecture overview with diagrams
-- Troubleshooting common issues
-- Contributing guidelines with commit conventions
-
-### Local Development & Self-Hosting
-
-**Quick Docker Setup**:
-```bash
-docker build -t youdotcom-mcp-server .
-docker run -d -p 4000:4000 --name youdotcom-mcp youdotcom-mcp-server
-```
-
-**Local Workspace Setup**:
-```bash
-# Clone and install
-git clone https://github.com/youdotcom-oss/youdotcom-mcp-server.git
-cd youdotcom-mcp-server
-bun install
-
-# Set up environment
-echo "export YDC_API_KEY=your-api-key-here" > .env
-source .env
-
-# Run development server (stdio mode)
-bun run dev
-
-# Or run HTTP server (port 4000)
-bun start
-```
-
-For detailed instructions on building from source, running in different modes, and deployment options, see [AGENTS.md](./AGENTS.md).
-
-### Quick Links
-
-- **Developer Guide**: [AGENTS.md](./AGENTS.md) - Complete technical reference
-- **Report Issues**: [GitHub Issues](https://github.com/youdotcom-oss/youdotcom-mcp-server/issues)
-- **Source Code**: [GitHub Repository](https://github.com/youdotcom-oss/youdotcom-mcp-server)
-- **API Documentation**: [You.com Docs](https://documentation.you.com/get-started/welcome)
-
-### How to Contribute
+Need technical details? Check [AGENTS.md](./AGENTS.md) for complete development setup, architecture overview, code patterns, and testing guidelines.
 
 1. Fork the repository
-2. Create a feature branch following naming conventions in AGENTS.md
+2. Create a feature branch following naming conventions in [CONTRIBUTING.md](./CONTRIBUTING.md) 
 3. Follow the code style guidelines and use conventional commits
 4. Write tests for your changes (maintain >80% coverage)
 5. Run quality checks: `bun run check && bun test`