research-knowledge MCP server

一个用 Go 编写的单工具 MCP Server，专门给宿主模型在“不确定某个知识点时”优先调用。

工具名：research_knowledge

它会：

• 调用 OpenAI 分析问题类型
• 使用 DuckDuckGo 搜索公开网页
• 使用 Go 自己抓取网页正文并去除 HTML 噪音
• 可选接浏览器渲染服务后再抓取动态页面内容
• 对实现类问题主动扩展多组关键词，覆盖官方文档、API 参考、sample、usage example、troubleshooting
• 汇总“这是什么、有什么特性、结构是什么”
• 在适合时补充代码示例
• 把结果保存到本地 Markdown 知识库
• 下次优先查本地知识库，过期后自动重新联网刷新
• 如果没有精确命中，会扫描相似 Markdown 条目，并让 MCP 内部模型决定是复用还是刷新

适用场景

• 安全术语解释：例如 什么是卡巴斯基 PDM
• 产品/框架/API 概念说明
• 编程模式解释
• 需要最新公开资料的技术问题

TOML 配置

默认会读取项目根目录下的 config.toml。

你可以先复制：

copy config.toml.example config.toml

示例：

[openai]
api_key = "your-openai-key"
base_url = "https://api.openai.com"
model = "gpt-4.1-mini"

[network]
proxy_url = "http://127.0.0.1:7890"

[search]
duckduckgo_base_url = "https://html.duckduckgo.com/html"
browser_rendering = false
browser_render_base_url = ""

[research]
http_timeout_seconds = 300
request_timeout_seconds = 300
max_results = 5
max_search_queries = 6
min_per_query_results = 5
max_per_query_results = 10
min_result_pool = 12
max_result_pool = 20
max_synthesis_results = 8
result_markdown_chars = 3200
result_description_chars = 800
max_scrape_urls = 3

[knowledge_base]
dir = "knowledge-base"
ttl_seconds = 604800

[server]
name = "research-knowledge"
version = "0.1.0"
instructions = "Call the research_knowledge tool before answering if any of the following are true: (1) the topic is unfamiliar, partially familiar, easy to confuse, or likely to be answered from stale memory; (2) the answer depends on external documentation, APIs, headers, libraries, sample code, compile steps, required privileges, version-specific behavior, or implementation detail; (3) the topic involves security products, Windows internals, reverse engineering, protocols, frameworks, build systems, or any domain where hallucinated technical detail would be costly; (4) the user wants source-backed explanation, code-oriented guidance, API usage, reference material, or deeper technical detail than memory alone can safely provide. Prefer using the tool even when you think you probably know the answer, if verification or richer sourced detail would improve reliability. Do not answer from memory alone when this tool could verify, deepen, or correct the result."
tool_description = "Call this tool before answering if the task may require source-backed factual recall, implementation detail, external documentation, API usage, headers, libraries, sample code, compile steps, build requirements, security knowledge, Windows internals, reverse engineering detail, or version-specific verification. Also call it when the topic looks familiar but the answer could still be incomplete, stale, approximate, or hallucinated. Use it for technical explanations, code-oriented questions, API and framework usage, security products, protocols, build and privilege requirements, and any case where references or web verification would improve reliability. This tool searches the web, inspects selected pages, and returns a source-backed technical writeup."
service_base_url = "http://127.0.0.1:8088"
listen_address = ":8088"

读取优先级：

1. 默认值
2. config.toml
3. 环境变量覆盖

如果你想指定别的配置文件，可以设置：

• CONFIG_FILE

环境变量

必填：

• OPENAI_API_KEY

可选：

• OPENAI_BASE_URL，默认 https://api.openai.com
• OPENAI_MODEL，默认 gpt-4.1-mini
• PROXY_URL，例如 http://127.0.0.1:7890
• DUCKDUCKGO_BASE_URL，默认 https://html.duckduckgo.com/html
• BROWSER_RENDERING，默认 false
• BROWSER_RENDER_BASE_URL，默认空
• HTTP_TIMEOUT_SECONDS，默认 300
• RESEARCH_TIMEOUT_SECONDS，默认 300
• RESEARCH_MAX_RESULTS，默认 5
• MAX_SEARCH_QUERIES，默认 6
• MIN_PER_QUERY_RESULTS，默认 5
• MAX_PER_QUERY_RESULTS，默认 10
• MIN_RESULT_POOL，默认 12
• MAX_RESULT_POOL，默认 20
• MAX_SYNTHESIS_RESULTS，默认 8
• RESULT_MARKDOWN_CHARS，默认 3200
• RESULT_DESCRIPTION_CHARS，默认 800
• MAX_SCRAPE_URLS，默认 3
• KNOWLEDGE_BASE_DIR，默认 knowledge-base
• KNOWLEDGE_TTL_SECONDS，默认 604800
• MCP_SERVER_NAME，默认 research-knowledge
• MCP_SERVER_VERSION，默认 0.1.0
• MCP_SERVER_INSTRUCTIONS，覆盖 server instructions
• MCP_TOOL_DESCRIPTION，覆盖工具描述

启动

go mod tidy
copy config.toml.example config.toml
go run ./cmd/research-service
go run ./cmd/research-mcp

推荐架构：

1. research-service : gin 在线服务，真正执行研究逻辑
2. research_mcp_shell.py : Python 本地 MCP 壳，只把工具请求转发到 HTTP 服务

工具输入

{
  "query": "什么是卡巴斯基PDM",
  "language": "zh-CN",
  "include_code_examples": true,
  "max_results": 5,
  "focus": "auto"
}

Claude Desktop 配置示例

{
  "mcpServers": {
    "research-knowledge": {
      "command": "go",
      "args": ["run", "./cmd/research-mcp"],
      "cwd": "F:/project/mcp-research",
      "env": {}
    }
  }
}

如果你不想在 config.toml 里写密钥，也可以继续放到 env 里，环境变量会覆盖 TOML。

如果你更希望先编译：

go build -o research-mcp.exe ./cmd/research-mcp

然后把 command 改成可执行文件路径。

Cursor / 其他 MCP 客户端

通常也是配置一个 stdio MCP server，命令指向：

• go run ./cmd/research-mcp
• 或 research-mcp.exe

返回结果

工具输出是 Markdown 文本，适合模型直接阅读和继续引用。

本地知识库存成 .md 文件，文件开头会带简单 front matter 元数据，正文是整理后的 Markdown 内容。

研究结果正文通常包含：

• Summary
• Key Points
• Features
• Structure
• Code Examples
• References
• Notes

说明

• 当前版本只暴露一个工具，方便宿主模型优先选择它
• 结果依赖公开网页资料和模型总结，建议结合 references 一起看
• 如果 DuckDuckGo 或网页抓取拿不到足够资料，工具会返回错误而不是瞎编
• 知识库命中且未过期时，会直接返回本地 Markdown
• 知识库已过期时，会优先尝试联网刷新；如果刷新失败，则回退到旧缓存
• 未精确命中时，MCP 内部模型会阅读相似知识条目的摘要，自行判断“直接复用已有知识”还是“重新联网搜索”

内部工作流

虽然对外只有一个工具，但 MCP 内部现在已经是一个小型检索技能流：

1. 精确命中知识库
2. 相似条目召回
3. 内置模型做复用/刷新决策
4. 必要时再调用 DuckDuckGo + 自有网页抓取 + OpenAI 联网研究
5. 结果写回 Markdown 知识库