@jhzhu89/mcp-server-web-search 0.0.1 → 0.1.1

package/README.md

@@ -0,0 +1,114 @@
+# @jhzhu89/mcp-server-web-search
+
+MCP Server for web search via Azure OpenAI Responses API with `web_search_preview` tool.
+
+## Installation
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime installed
+
+### Claude Code (Recommended)
+
+```bash
+# Install globally (available in all projects)
+claude mcp add web-search bunx @jhzhu89/mcp-server-web-search \
+  -s user \
+  -e AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
+  -e AZURE_OPENAI_DEPLOYMENT=gpt-5-mini
+
+# Or install for current project only (default)
+claude mcp add web-search bunx @jhzhu89/mcp-server-web-search \
+  -e AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
+  -e AZURE_OPENAI_DEPLOYMENT=gpt-5-mini
+```
+
+### Manual Configuration
+
+Add to your `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "web-search": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@jhzhu89/mcp-server-web-search"],
+      "env": {
+        "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com",
+        "AZURE_OPENAI_DEPLOYMENT": "gpt-5-mini"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `AZURE_OPENAI_ENDPOINT` | ✓ | - | Azure OpenAI endpoint URL |
+| `AZURE_OPENAI_DEPLOYMENT` | | `gpt-5-mini` | Deployment name |
+| `AZURE_OPENAI_API_VERSION` | | `2025-03-01-preview` | API version |
+
+## Authentication
+
+This server uses [DefaultAzureCredential](https://learn.microsoft.com/en-us/javascript/api/@azure/identity/defaultazurecredential) for Azure authentication. Supported methods:
+
+1. **Azure CLI** (local development): Run `az login` before starting
+2. **Environment variables**: Set `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`
+3. **Managed Identity**: Works automatically in Azure environments
+
+## Tool: web_search
+
+Search the web for real-time information with source citations.
+
+### Input
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | ✓ | Search query |
+| `search_context_size` | `"low"` \| `"medium"` \| `"high"` | | Amount of context (default: `"medium"`) |
+| `user_location` | object | | `{type, city, country, region, timezone}` for localized results |
+
+### Output (structuredContent)
+
+```json
+{
+  "results": [
+    {
+      "query": "original search query",
+      "text": "Answer text with inline [citations](url)...",
+      "citations": [
+        {
+          "title": "Source Title",
+          "url": "https://example.com",
+          "start_index": 0,
+          "end_index": 100
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Development
+
+```bash
+# Clone and install
+bun install
+
+# Run locally
+export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
+az login
+bun run start
+
+# Run with HTTP transport
+bun run start:http
+
+# Test
+bun test
+```
+
+## License
+
+MIT

package/package.json

@@ -1,8 +1,42 @@
-{
-  "name": "@jhzhu89/mcp-server-web-search",
-  "version": "0.0.1",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@jhzhu89/mcp-server-web-search",
+  "version": "0.1.1",
+  "description": "MCP Server providing web search via Azure OpenAI Responses API",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jiahao Zhu <jiahzhu@outlook.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jhzhu89/mcp-server-web-search"
+  },
+  "bin": {
+    "mcp-server-web-search": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "start:http": "bun run src/index.ts -- --http",
+    "dev": "bun --watch run src/index.ts -- --http",
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "test": "bun test",
+    "format": "prettier --write src test",
+    "lint": "eslint src",
+    "release:patch": "npm version patch && git push && git push --tags",
+    "release:minor": "npm version minor && git push && git push --tags",
+    "release:major": "npm version major && git push && git push --tags"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.13.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "openai": "^6.16.0",
+    "zod": "^3.25.61"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/bun": "latest",
+    "dotenv": "^17.2.3",
+    "typescript-eslint": "^8.33.1"
+  }
+}

package/src/azure-openai.ts

@@ -0,0 +1,49 @@
+import { AzureOpenAI } from "openai";
+import {
+  DefaultAzureCredential,
+  getBearerTokenProvider,
+} from "@azure/identity";
+import type {
+  Response,
+  WebSearchPreviewTool,
+} from "openai/resources/responses/responses";
+
+const credential = new DefaultAzureCredential();
+const client = new AzureOpenAI({
+  azureADTokenProvider: getBearerTokenProvider(
+    credential,
+    "https://cognitiveservices.azure.com/.default",
+  ),
+  apiVersion: process.env.AZURE_OPENAI_API_VERSION ?? "2025-03-01-preview",
+});
+
+const deployment = process.env.AZURE_OPENAI_DEPLOYMENT ?? "gpt-5-mini";
+
+export async function webSearch(
+  query: string,
+  searchContextSize: "low" | "medium" | "high" = "medium",
+  userLocation?: WebSearchPreviewTool.UserLocation,
+): Promise<Response> {
+  return client.responses.create({
+    model: deployment,
+    input: query,
+    instructions: `You are a web search tool. Your ONLY job is to search the web and return the search results directly.
+
+CRITICAL RULES:
+- NEVER ask clarifying questions or seek confirmation
+- NEVER offer options like "Which would you like?" or "Do you want me to..."
+- NEVER use conversational phrases or confirmatory language
+- ALWAYS perform the search immediately and return the results
+- Present information directly and factually from search results
+- Include relevant citations and sources
+- Be comprehensive but concise`,
+    tools: [
+      {
+        type: "web_search_preview",
+        search_context_size: searchContextSize,
+        user_location: userLocation,
+      },
+    ],
+    tool_choice: { type: "web_search_preview" },
+  });
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import { server } from "./server.js";
+
+if (process.argv.includes("--http")) {
+  const { WebStandardStreamableHTTPServerTransport } =
+    await import("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
+  const transport = new WebStandardStreamableHTTPServerTransport();
+  const port = Number(process.env.MCP_SERVER_PORT) || 3001;
+
+  await server.connect(transport);
+  Bun.serve({
+    port,
+    idleTimeout: 255,
+    fetch: (req) => {
+      if (new URL(req.url).pathname === "/mcp")
+        return transport.handleRequest(req);
+      return new Response("Not Found", { status: 404 });
+    },
+  });
+  console.log(`MCP Server: http://0.0.0.0:${port}/mcp`);
+} else {
+  const { StdioServerTransport } =
+    await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/server.ts

@@ -0,0 +1,102 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { webSearch } from "./azure-openai.js";
+import pkg from "../package.json" with { type: "json" };
+
+export const server = new McpServer({
+  name: pkg.name,
+  version: pkg.version,
+});
+
+// Output schema for structured content
+const citationSchema = z.object({
+  title: z.string().describe("Title of the source"),
+  url: z.string().describe("URL of the source"),
+  start_index: z.number().describe("Start character index in text"),
+  end_index: z.number().describe("End character index in text"),
+});
+
+const searchResultSchema = z.object({
+  query: z
+    .string()
+    .optional()
+    .describe("Original search query (first item only)"),
+  text: z.string().describe("Search result text with inline citations"),
+  citations: z.array(citationSchema).describe("Source citations for the text"),
+});
+
+const outputSchema = z.object({
+  results: z.array(searchResultSchema),
+});
+
+server.registerTool(
+  "web_search",
+  {
+    description:
+      "Search the web for real-time information. Returns results with source citations.",
+    inputSchema: {
+      query: z.string().describe("The search query"),
+      search_context_size: z
+        .enum(["low", "medium", "high"])
+        .default("medium")
+        .describe("Amount of search context"),
+      user_location: z
+        .object({
+          type: z.literal("approximate"),
+          city: z.string().nullish(),
+          country: z.string().nullish(),
+          region: z.string().nullish(),
+          timezone: z.string().nullish(),
+        })
+        .optional()
+        .describe("User location for localized results"),
+    },
+    outputSchema,
+  },
+  async ({ query, search_context_size, user_location }) => {
+    try {
+      const response = await webSearch(
+        query,
+        search_context_size,
+        user_location,
+      );
+
+      // Extract message content, keep structure but only useful fields
+      const message = response.output.find(
+        (item): item is Extract<typeof item, { type: "message" }> =>
+          item.type === "message",
+      );
+
+      const results = (message?.content ?? [])
+        .filter(
+          (c): c is Extract<typeof c, { type: "output_text" }> =>
+            c.type === "output_text",
+        )
+        .map(({ text, annotations }, index) => ({
+          ...(index === 0 ? { query } : {}),
+          text,
+          citations: annotations
+            .filter(
+              (a): a is Extract<typeof a, { type: "url_citation" }> =>
+                a.type === "url_citation",
+            )
+            .map(({ title, url, start_index, end_index }) => ({
+              title,
+              url,
+              start_index,
+              end_index,
+            })),
+        }));
+
+      return {
+        content: [],
+        structuredContent: { results },
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${String(error)}` }],
+        isError: true,
+      };
+    }
+  },
+);