opc-agent 2.0.2 → 3.0.0

package/src/tools/integrations/jira.ts

@@ -0,0 +1,83 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const JiraTool: MCPTool = {
+  name: 'jira',
+  description: 'Interact with Jira: create issues, update status, search, add comments. Requires JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN env vars.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['create_issue', 'update_status', 'search', 'add_comment'], description: 'Action to perform' },
+      project: { type: 'string', description: 'Project key (for create_issue)' },
+      summary: { type: 'string', description: 'Issue summary' },
+      description: { type: 'string', description: 'Issue description' },
+      issue_type: { type: 'string', description: 'Issue type (default: Task)' },
+      issue_key: { type: 'string', description: 'Issue key (e.g., PROJ-123)' },
+      status: { type: 'string', description: 'Target status (for update_status)' },
+      comment: { type: 'string', description: 'Comment text' },
+      jql: { type: 'string', description: 'JQL query (for search)' },
+    },
+    required: ['action'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const baseUrl = process.env.JIRA_URL;
+    const email = process.env.JIRA_EMAIL;
+    const apiToken = process.env.JIRA_API_TOKEN;
+    if (!baseUrl || !email || !apiToken) return { content: 'Error: JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN required', isError: true };
+
+    const auth = Buffer.from(`${email}:${apiToken}`).toString('base64');
+    const headers = { 'Authorization': `Basic ${auth}`, 'Content-Type': 'application/json', 'Accept': 'application/json' };
+    const action = String(input.action ?? '');
+
+    try {
+      if (action === 'create_issue') {
+        if (!input.project || !input.summary) return { content: 'Error: project, summary required', isError: true };
+        const res = await fetch(`${baseUrl}/rest/api/3/issue`, {
+          method: 'POST', headers,
+          body: JSON.stringify({
+            fields: {
+              project: { key: input.project },
+              summary: input.summary,
+              description: input.description ? { type: 'doc', version: 1, content: [{ type: 'paragraph', content: [{ type: 'text', text: String(input.description) }] }] } : undefined,
+              issuetype: { name: String(input.issue_type ?? 'Task') },
+            },
+          }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: `Issue created: ${data.key}` };
+      }
+
+      if (action === 'update_status') {
+        if (!input.issue_key || !input.status) return { content: 'Error: issue_key, status required', isError: true };
+        const trRes = await fetch(`${baseUrl}/rest/api/3/issue/${input.issue_key}/transitions`, { headers });
+        const trData = await trRes.json() as { transitions: Array<{ id: string; name: string }> };
+        const transition = trData.transitions?.find((t) => t.name.toLowerCase() === String(input.status).toLowerCase());
+        if (!transition) return { content: `No transition found for status: ${input.status}`, isError: true };
+        await fetch(`${baseUrl}/rest/api/3/issue/${input.issue_key}/transitions`, {
+          method: 'POST', headers, body: JSON.stringify({ transition: { id: transition.id } }),
+        });
+        return { content: `${input.issue_key} moved to ${input.status}` };
+      }
+
+      if (action === 'search') {
+        if (!input.jql) return { content: 'Error: jql required', isError: true };
+        const res = await fetch(`${baseUrl}/rest/api/3/search?jql=${encodeURIComponent(String(input.jql))}&maxResults=20`, { headers });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2).slice(0, 4000) };
+      }
+
+      if (action === 'add_comment') {
+        if (!input.issue_key || !input.comment) return { content: 'Error: issue_key, comment required', isError: true };
+        await fetch(`${baseUrl}/rest/api/3/issue/${input.issue_key}/comment`, {
+          method: 'POST', headers,
+          body: JSON.stringify({ body: { type: 'doc', version: 1, content: [{ type: 'paragraph', content: [{ type: 'text', text: String(input.comment) }] }] } }),
+        });
+        return { content: `Comment added to ${input.issue_key}` };
+      }
+
+      return { content: `Unknown action: ${action}`, isError: true };
+    } catch (err) {
+      return { content: `Jira error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/notion.ts

@@ -0,0 +1,71 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const NotionTool: MCPTool = {
+  name: 'notion',
+  description: 'Interact with Notion API: create pages, search, append blocks. Requires NOTION_API_KEY env var.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['create_page', 'search', 'append_block'], description: 'Action to perform' },
+      parent_id: { type: 'string', description: 'Parent page/database ID' },
+      title: { type: 'string', description: 'Page title (for create_page)' },
+      content: { type: 'string', description: 'Content text (for create_page or append_block)' },
+      query: { type: 'string', description: 'Search query (for search)' },
+      block_id: { type: 'string', description: 'Block ID (for append_block)' },
+    },
+    required: ['action'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const apiKey = process.env.NOTION_API_KEY;
+    if (!apiKey) return { content: 'Error: NOTION_API_KEY required', isError: true };
+
+    const action = String(input.action ?? '');
+    const headers = {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+      'Notion-Version': '2022-06-28',
+    };
+
+    try {
+      if (action === 'create_page') {
+        if (!input.parent_id) return { content: 'Error: parent_id required', isError: true };
+        const res = await fetch('https://api.notion.com/v1/pages', {
+          method: 'POST', headers,
+          body: JSON.stringify({
+            parent: { page_id: input.parent_id },
+            properties: { title: { title: [{ text: { content: String(input.title ?? 'Untitled') } }] } },
+            children: input.content ? [{ object: 'block', type: 'paragraph', paragraph: { rich_text: [{ text: { content: String(input.content) } }] } }] : [],
+          }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: `Page created: ${data.id ?? 'unknown'}` };
+      }
+
+      if (action === 'search') {
+        const res = await fetch('https://api.notion.com/v1/search', {
+          method: 'POST', headers,
+          body: JSON.stringify({ query: String(input.query ?? '') }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2).slice(0, 4000) };
+      }
+
+      if (action === 'append_block') {
+        if (!input.block_id) return { content: 'Error: block_id required', isError: true };
+        const res = await fetch(`https://api.notion.com/v1/blocks/${input.block_id}/children`, {
+          method: 'PATCH', headers,
+          body: JSON.stringify({
+            children: [{ object: 'block', type: 'paragraph', paragraph: { rich_text: [{ text: { content: String(input.content ?? '') } }] } }],
+          }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: `Block appended: ${JSON.stringify(data).slice(0, 500)}` };
+      }
+
+      return { content: `Unknown action: ${action}`, isError: true };
+    } catch (err) {
+      return { content: `Notion error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/npm-tool.ts

@@ -0,0 +1,48 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const NpmTool: MCPTool = {
+  name: 'npm',
+  description: 'Search npm registry, get package info, or list installed packages.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['search', 'info', 'install'], description: 'Action' },
+      package: { type: 'string', description: 'Package name' },
+      query: { type: 'string', description: 'Search query (for search)' },
+    },
+    required: ['action'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const action = String(input.action ?? '');
+
+    try {
+      if (action === 'search') {
+        const q = String(input.query ?? input.package ?? '');
+        if (!q) return { content: 'Error: query required', isError: true };
+        const res = await fetch(`https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(q)}&size=10`);
+        const data = await res.json() as { objects?: Array<{ package: { name: string; version: string; description: string } }> };
+        const results = (data.objects ?? []).map((o) => `${o.package.name}@${o.package.version} — ${o.package.description}`).join('\n');
+        return { content: results || 'No results' };
+      }
+
+      if (action === 'info') {
+        const pkg = String(input.package ?? '');
+        if (!pkg) return { content: 'Error: package required', isError: true };
+        const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`);
+        if (!res.ok) return { content: `Package not found: ${pkg}`, isError: true };
+        const data = await res.json() as Record<string, unknown>;
+        const latest = (data['dist-tags'] as Record<string, string>)?.latest;
+        return { content: `${data.name}@${latest}\n${data.description}\nLicense: ${data.license}\nHomepage: ${data.homepage}` };
+      }
+
+      if (action === 'install') {
+        return { content: 'Error: npm install is not supported via this tool for security. Use shell access instead.', isError: true };
+      }
+
+      return { content: `Unknown action: ${action}`, isError: true };
+    } catch (err) {
+      return { content: `NPM error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/pdf-reader.ts

@@ -0,0 +1,58 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+import * as fs from 'fs';
+
+export const PDFReaderTool: MCPTool = {
+  name: 'pdf-reader',
+  description: 'Extract text content from a PDF file. Uses basic binary parsing (no external deps).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: 'Path to PDF file' },
+      url: { type: 'string', description: 'URL of PDF file (alternative to file_path)' },
+      max_length: { type: 'number', description: 'Max characters to return (default: 5000)' },
+    },
+    required: [],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const maxLen = Number(input.max_length ?? 5000);
+
+    try {
+      let buffer: Buffer;
+
+      if (input.url) {
+        const res = await fetch(String(input.url));
+        if (!res.ok) return { content: `HTTP ${res.status}`, isError: true };
+        buffer = Buffer.from(await res.arrayBuffer());
+      } else if (input.file_path) {
+        buffer = fs.readFileSync(String(input.file_path));
+      } else {
+        return { content: 'Error: file_path or url required', isError: true };
+      }
+
+      // Basic PDF text extraction — find text between BT/ET markers and decode
+      const content = buffer.toString('latin1');
+      const textParts: string[] = [];
+
+      // Extract text from stream objects
+      const streamRegex = /stream\r?\n([\s\S]*?)\r?\nendstream/g;
+      let match: RegExpExecArray | null;
+      while ((match = streamRegex.exec(content)) !== null) {
+        const stream = match[1];
+        // Extract text shown with Tj or TJ operators
+        const tjRegex = /\(([^)]*)\)\s*Tj/g;
+        let tjMatch: RegExpExecArray | null;
+        while ((tjMatch = tjRegex.exec(stream)) !== null) {
+          textParts.push(tjMatch[1]);
+        }
+      }
+
+      const text = textParts.join(' ').replace(/\\n/g, '\n').replace(/\\\(/g, '(').replace(/\\\)/g, ')');
+      if (!text.trim()) return { content: '(No extractable text found — PDF may use compressed streams. Consider using a dedicated PDF library.)' };
+
+      return { content: text.slice(0, maxLen), metadata: { pages_approx: (content.match(/\/Type\s*\/Page[^s]/g) || []).length } };
+    } catch (err) {
+      return { content: `PDF error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/slack.ts

@@ -0,0 +1,65 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const SlackTool: MCPTool = {
+  name: 'slack',
+  description: 'Send messages to Slack channels, list channels, or search messages. Requires SLACK_WEBHOOK_URL or SLACK_BOT_TOKEN env var.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['send_message', 'list_channels', 'search'], description: 'Action to perform' },
+      channel: { type: 'string', description: 'Channel name or ID (for send_message)' },
+      text: { type: 'string', description: 'Message text (for send_message) or search query (for search)' },
+    },
+    required: ['action'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const action = String(input.action ?? '');
+    const token = process.env.SLACK_BOT_TOKEN;
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+
+    try {
+      if (action === 'send_message') {
+        if (!input.text) return { content: 'Error: text is required', isError: true };
+        if (webhookUrl) {
+          const res = await fetch(webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ channel: input.channel, text: input.text }),
+          });
+          return { content: `Message sent (status: ${res.status})` };
+        }
+        if (!token) return { content: 'Error: SLACK_BOT_TOKEN or SLACK_WEBHOOK_URL required', isError: true };
+        const res = await fetch('https://slack.com/api/chat.postMessage', {
+          method: 'POST',
+          headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ channel: input.channel, text: input.text }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: data.ok ? 'Message sent' : `Error: ${data.error}`, isError: !data.ok };
+      }
+
+      if (action === 'list_channels') {
+        if (!token) return { content: 'Error: SLACK_BOT_TOKEN required', isError: true };
+        const res = await fetch('https://slack.com/api/conversations.list', {
+          headers: { 'Authorization': `Bearer ${token}` },
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2) };
+      }
+
+      if (action === 'search') {
+        if (!token) return { content: 'Error: SLACK_BOT_TOKEN required', isError: true };
+        const res = await fetch(`https://slack.com/api/search.messages?query=${encodeURIComponent(String(input.text ?? ''))}`, {
+          headers: { 'Authorization': `Bearer ${token}` },
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2) };
+      }
+
+      return { content: `Unknown action: ${action}`, isError: true };
+    } catch (err) {
+      return { content: `Slack error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/summarizer.ts

@@ -0,0 +1,49 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const SummarizerTool: MCPTool = {
+  name: 'summarizer',
+  description: 'Summarize long text using an LLM API. Requires OPENAI_API_KEY or LLM_API_URL env var.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Text to summarize' },
+      max_length: { type: 'number', description: 'Approximate max summary length in words (default: 200)' },
+      style: { type: 'string', enum: ['brief', 'detailed', 'bullets'], description: 'Summary style (default: brief)' },
+    },
+    required: ['text'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const text = String(input.text ?? '');
+    if (!text) return { content: 'Error: text required', isError: true };
+
+    const style = String(input.style ?? 'brief');
+    const maxLen = Number(input.max_length ?? 200);
+    const prompt = `Summarize the following text in a ${style} style, approximately ${maxLen} words:\n\n${text.slice(0, 15000)}`;
+
+    try {
+      const apiKey = process.env.OPENAI_API_KEY;
+      const apiUrl = process.env.LLM_API_URL || 'https://api.openai.com/v1/chat/completions';
+      if (!apiKey && apiUrl === 'https://api.openai.com/v1/chat/completions') {
+        return { content: 'Error: OPENAI_API_KEY or LLM_API_URL required', isError: true };
+      }
+
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+      if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+
+      const res = await fetch(apiUrl, {
+        method: 'POST', headers,
+        body: JSON.stringify({
+          model: process.env.LLM_MODEL || 'gpt-4o-mini',
+          messages: [{ role: 'user', content: prompt }],
+          max_tokens: maxLen * 3,
+        }),
+      });
+      const data = await res.json() as { choices?: Array<{ message: { content: string } }> };
+      const summary = data.choices?.[0]?.message?.content ?? 'No summary generated';
+      return { content: summary };
+    } catch (err) {
+      return { content: `Summarizer error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/translator.ts

@@ -0,0 +1,48 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const TranslatorTool: MCPTool = {
+  name: 'translator',
+  description: 'Translate text between languages using an LLM. Requires OPENAI_API_KEY or LLM_API_URL env var.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Text to translate' },
+      from: { type: 'string', description: 'Source language (auto-detect if omitted)' },
+      to: { type: 'string', description: 'Target language (required)' },
+    },
+    required: ['text', 'to'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const text = String(input.text ?? '');
+    const to = String(input.to ?? '');
+    if (!text || !to) return { content: 'Error: text and to are required', isError: true };
+
+    const from = input.from ? ` from ${input.from}` : '';
+    const prompt = `Translate the following text${from} to ${to}. Return only the translation, no explanations:\n\n${text.slice(0, 10000)}`;
+
+    try {
+      const apiKey = process.env.OPENAI_API_KEY;
+      const apiUrl = process.env.LLM_API_URL || 'https://api.openai.com/v1/chat/completions';
+      if (!apiKey && apiUrl === 'https://api.openai.com/v1/chat/completions') {
+        return { content: 'Error: OPENAI_API_KEY or LLM_API_URL required', isError: true };
+      }
+
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+      if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+
+      const res = await fetch(apiUrl, {
+        method: 'POST', headers,
+        body: JSON.stringify({
+          model: process.env.LLM_MODEL || 'gpt-4o-mini',
+          messages: [{ role: 'user', content: prompt }],
+        }),
+      });
+      const data = await res.json() as { choices?: Array<{ message: { content: string } }> };
+      const translation = data.choices?.[0]?.message?.content ?? 'No translation generated';
+      return { content: translation };
+    } catch (err) {
+      return { content: `Translation error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/trello.ts

@@ -0,0 +1,60 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const TrelloTool: MCPTool = {
+  name: 'trello',
+  description: 'Interact with Trello: create cards, move cards, list boards. Requires TRELLO_API_KEY, TRELLO_TOKEN env vars.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['create_card', 'move_card', 'list_boards'], description: 'Action' },
+      list_id: { type: 'string', description: 'List ID (for create_card/move_card)' },
+      card_id: { type: 'string', description: 'Card ID (for move_card)' },
+      name: { type: 'string', description: 'Card name' },
+      description: { type: 'string', description: 'Card description' },
+    },
+    required: ['action'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const key = process.env.TRELLO_API_KEY;
+    const token = process.env.TRELLO_TOKEN;
+    if (!key || !token) return { content: 'Error: TRELLO_API_KEY, TRELLO_TOKEN required', isError: true };
+
+    const auth = `key=${key}&token=${token}`;
+    const action = String(input.action ?? '');
+
+    try {
+      if (action === 'create_card') {
+        if (!input.list_id || !input.name) return { content: 'Error: list_id, name required', isError: true };
+        const res = await fetch(`https://api.trello.com/1/cards?${auth}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ idList: input.list_id, name: input.name, desc: input.description ?? '' }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: `Card created: ${data.shortUrl ?? data.id}` };
+      }
+
+      if (action === 'move_card') {
+        if (!input.card_id || !input.list_id) return { content: 'Error: card_id, list_id required', isError: true };
+        await fetch(`https://api.trello.com/1/cards/${input.card_id}?${auth}`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ idList: input.list_id }),
+        });
+        return { content: `Card ${input.card_id} moved to list ${input.list_id}` };
+      }
+
+      if (action === 'list_boards') {
+        const res = await fetch(`https://api.trello.com/1/members/me/boards?${auth}`);
+        const data = await res.json() as Array<Record<string, unknown>>;
+        const summary = Array.isArray(data) ? data.map((b) => `${b.name} (${b.id})`).join('\n') : JSON.stringify(data);
+        return { content: summary };
+      }
+
+      return { content: `Unknown action: ${action}`, isError: true };
+    } catch (err) {
+      return { content: `Trello error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/vector-search.ts

@@ -0,0 +1,42 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const VectorSearchTool: MCPTool = {
+  name: 'vector-search',
+  description: 'Search vector embeddings via DeepBrain or compatible API. Requires DEEPBRAIN_URL and DEEPBRAIN_API_KEY env vars.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query text' },
+      collection: { type: 'string', description: 'Collection/namespace to search' },
+      top_k: { type: 'number', description: 'Number of results (default: 5)' },
+    },
+    required: ['query'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const baseUrl = process.env.DEEPBRAIN_URL;
+    const apiKey = process.env.DEEPBRAIN_API_KEY;
+    if (!baseUrl) return { content: 'Error: DEEPBRAIN_URL required', isError: true };
+
+    const query = String(input.query ?? '');
+    if (!query) return { content: 'Error: query required', isError: true };
+
+    try {
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+      if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+
+      const res = await fetch(`${baseUrl}/api/search`, {
+        method: 'POST', headers,
+        body: JSON.stringify({
+          query,
+          collection: input.collection ?? 'default',
+          top_k: Number(input.top_k ?? 5),
+        }),
+      });
+      const data = await res.json() as Record<string, unknown>;
+      return { content: JSON.stringify(data, null, 2).slice(0, 4000) };
+    } catch (err) {
+      return { content: `Vector search error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/web-scraper.ts

@@ -0,0 +1,47 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const WebScraperTool: MCPTool = {
+  name: 'web-scraper',
+  description: 'Fetch and extract readable content from a URL.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'URL to scrape' },
+      max_length: { type: 'number', description: 'Max characters to return (default: 5000)' },
+    },
+    required: ['url'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const url = String(input.url ?? '');
+    if (!url) return { content: 'Error: url required', isError: true };
+    const maxLen = Number(input.max_length ?? 5000);
+
+    try {
+      const res = await fetch(url, {
+        headers: { 'User-Agent': 'Mozilla/5.0 (compatible; OPCAgent/1.0)' },
+      });
+      if (!res.ok) return { content: `HTTP ${res.status}: ${res.statusText}`, isError: true };
+
+      const html = await res.text();
+      // Simple HTML to text extraction
+      const text = html
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+
+      const truncated = text.length > maxLen ? text.slice(0, maxLen) + '...(truncated)' : text;
+      return { content: truncated, metadata: { url, length: text.length } };
+    } catch (err) {
+      return { content: `Scraper error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};

package/src/tools/integrations/web-search.ts

@@ -0,0 +1,58 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const WebSearchTool: MCPTool = {
+  name: 'web-search',
+  description: 'Search the web using SerpAPI, Tavily, or Brave Search. Requires SERPAPI_KEY, TAVILY_API_KEY, or BRAVE_SEARCH_KEY env var.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+      provider: { type: 'string', enum: ['serpapi', 'tavily', 'brave'], description: 'Search provider (auto-detects from env)' },
+      count: { type: 'number', description: 'Number of results (default: 5)' },
+    },
+    required: ['query'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const query = String(input.query ?? '');
+    if (!query) return { content: 'Error: query required', isError: true };
+    const count = Number(input.count ?? 5);
+
+    try {
+      const provider = String(input.provider ?? '');
+      if (provider === 'tavily' || process.env.TAVILY_API_KEY) {
+        const key = process.env.TAVILY_API_KEY;
+        if (!key) return { content: 'Error: TAVILY_API_KEY required', isError: true };
+        const res = await fetch('https://api.tavily.com/search', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ api_key: key, query, max_results: count }),
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2).slice(0, 4000) };
+      }
+
+      if (provider === 'brave' || process.env.BRAVE_SEARCH_KEY) {
+        const key = process.env.BRAVE_SEARCH_KEY;
+        if (!key) return { content: 'Error: BRAVE_SEARCH_KEY required', isError: true };
+        const res = await fetch(`https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`, {
+          headers: { 'X-Subscription-Token': key, 'Accept': 'application/json' },
+        });
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2).slice(0, 4000) };
+      }
+
+      if (provider === 'serpapi' || process.env.SERPAPI_KEY) {
+        const key = process.env.SERPAPI_KEY;
+        if (!key) return { content: 'Error: SERPAPI_KEY required', isError: true };
+        const res = await fetch(`https://serpapi.com/search.json?q=${encodeURIComponent(query)}&num=${count}&api_key=${key}`);
+        const data = await res.json() as Record<string, unknown>;
+        return { content: JSON.stringify(data, null, 2).slice(0, 4000) };
+      }
+
+      return { content: 'Error: No search API key configured (TAVILY_API_KEY, BRAVE_SEARCH_KEY, or SERPAPI_KEY)', isError: true };
+    } catch (err) {
+      return { content: `Search error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};