@youdotcom-oss/mcp 3.3.0 → 3.4.0

package/README.md

@@ -1,266 +1,75 @@
-# You.com MCP Server
+# @youdotcom-oss/mcp
 
-Connect your AI agents to You.com's **hosted MCP service** for real-time web search, AI answers, and content extraction. [Model Context Protocol](https://modelcontextprotocol.io/) gives you one integration that works across IDEs, frameworks, and production systems. Use the remote server at `https://api.you.com/mcp` directly, or install this npm package as a lightweight STDIO bridge for clients that require a local process.
+Bin-only STDIO bridge for the hosted You.com MCP server at `https://api.you.com/mcp`.
 
-## Features
+This package does not register tools locally and does not contain REST tool logic. Its only job is to proxy STDIO MCP traffic to the hosted remote server.
 
-- **Web and news search**: Comprehensive search using You.com's unified Search API with advanced search operators
-- **Research**: Comprehensive answers with cited sources, configurable effort (lite to exhaustive)
-- **Content extraction**: Extract and retrieve full content from web pages in markdown or HTML format
-- **Multiple access methods**: Remote server (recommended) or local STDIO bridge
-- **Free tier**: Search works without an API key (rate-limited by IP)
-- **Advanced search parameters**: Site filtering, file type filtering, language filtering, exact terms, and exclude terms
-
-## Getting started
-
-Get up and running with the You.com MCP Server in 4 quick steps:
-
-### 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.
-
-> **Free tier**: Search works without an API key (rate-limited). API key required for contents and research tools.
-
-### 2. Choose your setup
-
-You can discover this server in the [Anthropic MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.youdotcom-oss/mcp`, or configure it manually:
-
-**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** - STDIO bridge to the remote server
-- Use `npx @youdotcom-oss/mcp` with STDIO transport
-- Authentication via `YDC_API_KEY` environment variable
-- Requires Bun or Node.js
-
-### 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 (recommended):**
-```json
-{
-  "mcpServers": {
-    "ydc-server": {
-      "type": "http",
-      "url": "https://api.you.com/mcp",
-      "headers": { "Authorization": "Bearer <you-api-key>" }
-    }
-  }
-}
-```
-
-**NPM package:**
-```json
-{
-  "mcpServers": {
-    "ydc-server": {
-      "command": "npx",
-      "args": ["@youdotcom-oss/mcp"],
-      "env": { "YDC_API_KEY": "<you-api-key>" }
-    }
-  }
-}
-```
-
-**Configuration notes:**
-- Remote server recommended for most users (no installation, always up-to-date)
-- NPM package for MCP clients that require local STDIO processes
-- `YDC_API_KEY` is optional — omit for free tier (search only, rate-limited)
-- `MCP_SERVER_URL` env var overrides the remote server URL (defaults to `https://api.you.com/mcp`)
-
-### 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"
-- "What is the capital of France?" (with web search)
-- "Extract the content from https://example.com"
-
-Your agent will automatically use the appropriate tool based on your natural language request.
-
-## Adding to your MCP client
-
-Use the configuration templates from [Getting Started](#getting-started) above with your client's MCP setup. Any MCP-compatible client follows the same pattern.
-
-<details>
-<summary><strong>Claude Code</strong></summary>
+## Install
 
 ```bash
-claude mcp add --transport http ydc-server https://api.you.com/mcp --header "Authorization: Bearer <your-api-key>"
+bun add @youdotcom-oss/mcp
 ```
 
-For full setup, see the MCP installation [guide](https://code.claude.com/docs/en/mcp).
-
-</details>
-
-<details>
-<summary><strong>Claude Desktop</strong></summary>
-
-Use the remote server configuration template from Step 3 above. For full setup, see the MCP installation [guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
-
-</details>
-
-<details>
-<summary><strong>Cursor IDE</strong></summary>
-
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ydc-server&config=eyJ1cmwiOiJodHRwczovL2FwaS55b3UuY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8eW91LWFwaS1rZXk%2BIn19)
-
-Use the configuration template above ***without the type field***. For full setup, see the [guide](https://cursor.com/docs/context/mcp#installing-mcp-servers).
-
-**Note:** To avoid conflicts, go to Settings > Agents tab and turn off Cursor's built-in web search tool.
-
-</details>
-
-<details>
-<summary><strong>VS Code</strong></summary>
+Or run it directly:
 
 ```bash
-code --add-mcp "{\"name\":\"ydc-server\",\"url\":\"https://api.you.com/mcp\",\"type\":\"http\",\"headers\":{\"Authorization\":\"Bearer <your-api-key>\"}}"
+npx @youdotcom-oss/mcp
 ```
 
-For full setup, see the MCP installation [guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server).
-
-</details>
-
-**Other clients** — use the configuration template from Step 3 with your client's MCP setup guide:
-- [Codex](https://github.com/openai/codex/blob/main/docs/config.md#streamable-http)
-- [Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html#how-to-set-up-your-mcp-server)
-- [JetBrains IDEs](https://www.jetbrains.com/help/ai-assistant/mcp.html#connect-to-an-mcp-server)
-- [LM Studio](https://lmstudio.ai/docs/app/mcp) *(omit type field)*
-- [opencode](https://opencode.ai/docs/mcp-servers/#remote)
-- [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin)
-- [Zed Editor](https://zed.dev/docs/ai/mcp#as-custom-servers) *(omit type field)*
-
-## Available tools
-
-This MCP server provides three tools that work seamlessly with your AI agent through natural language:
-
-### you-search
-Comprehensive web and news search with advanced filtering capabilities. Perfect for finding current information, research articles, documentation, and news stories.
-
-**When to use**: When you need to search the web for information, filter by specific sites/file types, or get the latest news on a topic.
-
-### you-research
-Research with comprehensive answers and cited sources. Configurable effort levels (lite, standard, deep, exhaustive) let you trade speed for thoroughness.
-
-**When to use**: When you need in-depth answers to complex questions, research reports with citations, or thorough analysis that goes beyond simple search results.
-
-### you-contents
-Extract full page content from URLs in markdown, HTML, or structured metadata formats. Useful for documentation analysis, content processing, SEO data extraction, and batch URL processing.
-
-**When to use**: When you need to extract web page content (markdown/HTML) or structured metadata (OpenGraph, JSON-LD) for analysis or processing in your workflow.
-
----
-
-**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
-
-Here are common scenarios showing when and how to use each tool with natural language queries:
-
-### Research & information gathering
-
-**Use you-search when:**
-- "Find recent research papers about quantum computing on arxiv.org"
-- "Search for TypeScript documentation about generics"
-- "Get the latest news about renewable energy from the past week"
-- "Find PDF files about machine learning algorithms"
-
-**Use you-research when:**
-- "Give me a comprehensive analysis of the current state of AI regulation"
-- "Research the pros and cons of WebAssembly vs JavaScript for performance-critical applications"
-- "What are the latest breakthroughs in quantum computing? Include sources."
-- "Provide a detailed comparison of React, Vue, and Svelte with citations"
+## Environment
 
-### Content extraction & analysis
+- `YDC_API_KEY`
+  Optional. Sent as `Authorization: Bearer <key>`.
+- `YDC_PROFILE`
+  Optional. When set to `free`, routes the bridge to `https://api.you.com/mcp?profile=free`.
+- `YDC_ALLOWED_TOOLS`
+  Optional. Comma-separated hosted tool ids to expose through `https://api.you.com/mcp?tools=...`.
 
-**Use you-contents when:**
-- "Extract the content from this blog post: https://example.com/article"
-- "Get the documentation from these three URLs in markdown format"
-- "Pull the HTML content from this page preserving the layout"
-- "Extract metadata from this article to get the author and publish date"
-- "Get OpenGraph preview data for social sharing from these URLs"
-- "Batch extract content from these 5 documentation pages"
+`YDC_PROFILE` takes precedence over `YDC_ALLOWED_TOOLS`.
 
-### Combined workflows
+## Tool exposure
 
-Your AI agent can combine multiple tools in a single conversation:
-1. **Search + Extract**: "Search for the best TypeScript tutorials, then extract the content from the top 3 results"
-2. **Research + Deep Dive**: "Research WebAssembly performance benefits, then extract code samples from the cited sources"
-3. **News + Research**: "Find recent articles about AI regulation, then research the policy implications"
+The hosted MCP capability surface includes:
 
-### Pro tips
+- `you-contents`
+- `you-finance`
+- `you-research`
+- `you-search`
 
-- **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
+The default hosted MCP URL exposes the default tool set:
 
-## Troubleshooting & support
+- `you-search`
+- `you-research`
+- `you-contents`
 
-### Common issues
+`you-finance` is not included in the default tool set. Request it explicitly with `tools`.
 
-**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
+`tools` scopes the visible tool set.
 
-**Tool not working:**
-- Check your MCP client logs for error messages
-- Verify your API key has the necessary permissions
-- For remote server: Ensure you can reach https://api.you.com/mcp-health
-- For local: Verify Bun or Node.js is installed and the package is properly set up
+Today, `profile=free` is a search-only mode. It overrides `tools` and does not expose `you-research`, `you-contents`, `you-finance`, or livecrawl.
 
-**Authentication errors:**
-- Remote server uses Bearer token authentication in headers
-- Local STDIO mode uses YDC_API_KEY environment variable
-- Make sure you're using the correct authentication method for your setup
+Examples:
 
-### Error logs
+- Default tool set: `https://api.you.com/mcp`
+- Finance only: `https://api.you.com/mcp?tools=you-finance`
+- Search plus finance: `https://api.you.com/mcp?tools=you-search,you-finance`
+- Free search profile: `https://api.you.com/mcp?profile=free`
 
-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
-- Claude Desktop: View logs in application menu
-- Cursor: Check MCP server logs in settings
-- VS Code: View Output panel for MCP server logs
+## Example client config
 
-### Report an issue
-
-If you encounter a problem, you can report it via email or GitHub:
-
-**Email support:** support@you.com
-
-**Web support:** [You.com Support](https://you.com/support/contact-us)
-
-**GitHub Issues:** [Report bugs and feature requests](https://github.com/youdotcom-oss/dx-toolkit/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
-
-Interested in contributing to the You.com MCP Server? We'd love your help!
-
-Need technical details? See the [mcp-patterns skill](../../.agents/skills/mcp-patterns/SKILL.md) for architecture, bridge maintenance patterns, and testing guidelines.
-
-**Publishing note**: npm publish (`.github/workflows/publish-mcp.yml`) is for STDIO bridge changes only — rarely needed. The Anthropic MCP Registry is updated separately via `.github/workflows/publish-registry.yml` when the remote server's public surface changes (tools, auth, URL).
-
-1. Fork the repository
-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`
-6. Submit a pull request with a clear description
-
-We appreciate all contributions, whether it's:
-- Bug fixes
-- New features
-- Documentation improvements
-- Performance optimizations
-- Test coverage improvements
-
----
+```json
+{
+  "mcpServers": {
+    "ydc": {
+      "command": "npx",
+      "args": ["@youdotcom-oss/mcp"],
+      "env": {
+        "YDC_API_KEY": "<your-api-key>",
+        "YDC_ALLOWED_TOOLS": "you-search,you-finance"
+      }
+    }
+  }
+}
+```
 
-**License**: MIT
-**Author**: You.com (https://you.com)
+Use the hosted HTTP server directly when your MCP client supports remote MCP. Use this package only when the client requires a local STDIO command.