@yexuan910812/finch-brave-search 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 henryye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# Brave Search for Finch
+
+通过 Brave Search API 为 Finch 提供实时网页搜索能力，返回网页标题、摘要与链接。
+
+## 功能
+
+- 支持中文与英文搜索
+- 每次返回 1–20 条结果
+- 适用于最新信息检索、资料查找与事实核验
+- API Key 仅通过 Finch 的安全密钥机制读取
+
+## 安装
+
+```bash
+npx @finchtoys/minitools add @yexuan910812/finch-brave-search
+```
+
+## 配置
+
+1. 前往 [Brave Search API](https://brave.com/search/api/) 获取 API Key。
+2. 在 Finch 为此 mini tool 配置 `BRAVE_API_KEY`。
+3. 如果尚未配置，首次搜索时会出现安全输入表单；输入值仅用于当前调用，不会返回给模型。
+
+## 工具
+
+### `brave_search_web_search`
+
+参数：
+
+- `query`：搜索关键词，必填
+- `count`：结果数量，1–20，默认 10
+
+## 权限
+
+- `network`：访问 Brave Search API
+- `secrets.BRAVE_API_KEY`：读取用户在 Finch 中安全配置的 API Key
+
+本项目不会把 API Key 写入日志、搜索结果或 npm 发布包。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type * as finch from 'finch';
+export declare function activate(ctx: finch.MiniToolContext): void;

package/dist/index.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+const BRAVE_SEARCH_API = 'https://api.search.brave.com/res/v1/web/search';
+function activate(ctx) {
+    ctx.subscriptions.push(ctx.tools.register({
+        name: 'brave_search_web_search',
+        title: '网页搜索 (Brave)',
+        description: '使用 Brave Search API 搜索互联网。当用户需要最新信息、查找特定资料、验证事实、搜索中文或国际内容时调用。返回标题、摘要和链接。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: '搜索关键词，支持中文和英文。尽量精确以获得更好的结果。',
+                },
+                count: {
+                    type: 'number',
+                    description: '返回结果数量（1-20，默认 10）',
+                    default: 10,
+                },
+            },
+            required: ['query'],
+        },
+        risk: 'low',
+        defaultEnabled: true,
+        async execute(input, exec) {
+            const query = String(input.query);
+            const count = Math.min(Math.max(Number(input.count) || 10, 1), 20);
+            // 获取 API Key
+            let apiKey = await exec.secrets.get('BRAVE_API_KEY');
+            // 如果没有 Key，弹表单让用户输入
+            if (!apiKey) {
+                const form = await exec.ui.requestForm({
+                    title: '配置 Brave Search API',
+                    description: '首次使用需要设置 Brave Search API Key。前往 https://brave.com/search/api/ 免费获取。',
+                    fields: [
+                        {
+                            key: 'apiKey',
+                            label: 'API Key',
+                            type: 'password',
+                            secret: true,
+                            placeholder: '输入你的 Brave Search API Key',
+                            required: true,
+                            width: '2/3',
+                        },
+                        {
+                            key: 'signup',
+                            label: '免费获取 API Key',
+                            type: 'link',
+                            href: 'https://brave.com/search/api/',
+                            width: '1/3',
+                        },
+                    ],
+                    submitLabel: '使用并搜索',
+                    cancelLabel: '取消',
+                });
+                if (!form.submitted) {
+                    return {
+                        content: [{ type: 'text', text: '用户取消了 Brave Search API Key 设置，无法完成搜索。' }],
+                        isError: true,
+                    };
+                }
+                apiKey = String(form.values.apiKey);
+            }
+            // 发起 Brave Search 请求
+            try {
+                const url = new URL(BRAVE_SEARCH_API);
+                url.searchParams.set('q', query);
+                url.searchParams.set('count', String(count));
+                const response = await fetch(url.toString(), {
+                    headers: {
+                        'X-Subscription-Token': apiKey,
+                        'Accept': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    if (response.status === 401 || response.status === 403) {
+                        return {
+                            content: [{ type: 'text', text: `Brave Search API 认证失败（${response.status}）。请检查 API Key 是否正确，或前往 https://brave.com/search/api/ 重新获取。` }],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [{ type: 'text', text: `Brave Search API 请求失败：HTTP ${response.status} ${response.statusText}` }],
+                        isError: true,
+                    };
+                }
+                const data = (await response.json());
+                if (!data.web?.results || data.web.results.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: `关于"${query}"未找到相关结果。` }],
+                    };
+                }
+                // 格式化结果
+                const lines = [
+                    `## 搜索结果 — "${data.query?.original || query}"`,
+                    '',
+                ];
+                for (const r of data.web.results) {
+                    lines.push(`### [${r.title}](${r.url})`);
+                    lines.push(`${r.description || '(无摘要)'}`);
+                    lines.push('');
+                }
+                lines.push(`---\n共 ${data.web.results.length} 条结果`);
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: `搜索请求出错：${err instanceof Error ? err.message : String(err)}` }],
+                    isError: true,
+                };
+            }
+        },
+    }));
+    ctx.logger.info('Brave Search mini tool activated');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@yexuan910812/finch-brave-search",
+  "version": "1.0.0",
+  "description": "Brave Search API 网页搜索 mini tool for Finch",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "icon.png",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "finch",
+    "finch-mini-tool",
+    "brave-search",
+    "web-search",
+    "ai-agent"
+  ],
+  "author": "henryye",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "finch": {
+    "manifestVersion": 1,
+    "id": "brave-search",
+    "name": "Brave Search",
+    "description": "通过 Brave Search API 搜索互联网，获取最新网页结果。",
+    "miniToolType": "community",
+    "main": "dist/index.js",
+    "activationEvents": [
+      "onStartup"
+    ],
+    "contributes": {
+      "tools": true
+    },
+    "permissions": {
+      "network": true,
+      "secrets": [
+        "BRAVE_API_KEY"
+      ]
+    }
+  },
+  "devDependencies": {
+    "@finchtoys/minitool-api": "^0.1.17",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
+  }
+}