内容
# 🧠 idea-box-mcp
> **使用自然语言搜索并添加内容到本地 Markdown 知识库（idea-box + memo-box）。**
[](LICENSE)
[](https://www.python.org)
[](https://modelcontextprotocol.io)
[](https://github.com/nerin81-netizen/idea-box-mcp/stargazers)
**🌍 阅读您的语言版本：** [English](README.md) · [한국어](README.ko.md) · [中文](README.zh.md) · [日本語](README.ja.md) · [Español](README.es.md) · [Français](README.fr.md) · [हिन्दी](README.hi.md) · [العربية](README.ar.md)
[🚀 快速开始](#-quickstart) · [🛠 工具](#-tools-5) · [🎬 演示](#-demo) · [🏗 架构](#-architecture) · [🧪 开发](#-development)
---
## ✨ 这是什么
**您有许多 Markdown 文件夹。** 您在这些文件夹中收集了许多想法、备忘录和链接。但是，当您需要时，却很难找到正确的文件。
`idea-box-mcp` 将您的本地 Markdown 文件夹转换为 **LLM 可调用的工具**。不再需要手动搜索：
```bash
# ❌ 之前：手动搜索
grep -r "AI" ~/ideas-h/
find ~/memos-h/ -name "*.md" -exec grep -l "arxiv" {} \;
```
您可以直接问：
```text
# ✅ 之后：自然语言搜索
"AI 相关想法 찾아줘"
"arxiv 메모 보여줘"
"메모해 — 이 링크 나중에 봐야 해"
```
**两个目录：**
| 目录 | 内容 | 使用场景 |
|---|---|---|
| `~/ideas-h/` | 应用程序想法，带有状态/等级 | "我应该构建什么？" |
| `~/memos-h/` | 原始参考资料（8 个类别） | "我之前保存了什么？" |
> **核心思想：** 您的本地 Markdown 文件夹已经是一个知识库。这个 MCP 只是使它们可以被 LLM 查询。
## 🛠 工具（5）
| 工具 | 参数 | 描述 | 示例提示 |
|---|---|---|---|
| `search_ideas` | `keyword`, `limit` | 按关键词搜索 idea-box | "AI 相关想法 찾아줘" |
| `count_ideas` | — | 统计数据（总数，按等级，最近） | "내 아이디어 몇 개야?" |
| `search_memos` | `keyword`, `category`, `limit` | 搜索 memo-box（8 个类别） | "arxiv 메모 찾아줘" |
| `count_memos` | — | 统计数据（总数，按类别） | "메모박스 통계" |
| `add_memo` | `title`, `content`, `category`, `tags` | 添加新备忘录并自动分类 | "메모해 — ..." |
### 现实场景
**场景 1: "这个健康跟踪的想法是什么？"**
您记得两周前写了关于健康应用程序的内容，但找不到。直接问：
```text
"건강 관련 아이디어 찾아줘"
→ 🔍 '건강' 搜索结果 — 3 个 / 总共 145 个
· **健康数据整合应用程序** [B]
医院/药店/保险数据整合到一个地方...
📁 `2026-06-15_健康数据整合应用程序.md`
· **服药提醒 + 相互作用检查**
服药时检查副作用的应用程序...
📁 `2026-06-20_服药提醒.md`
```
**场景 2: "保存此内容以备后用"**
您在浏览时发现了一些有趣的内容。不要 bookmark（然后忘记），直接问：
```text
"메모해 — vLLM 서빙 튜토리얼: https://vllm.readthedocs.io/en/latest/
标签: mlops, inference, vllm"
→ ✅ 保存完成: `links/2026-07-06_vLLM 서빙 튜토리얼.md`
类别: 🔗 链接
```
稍后，您可以问：
```text
"inference 相关 메모 찾아줘"
→ 🔍 备忘录搜索 — 2 个 / 总共 11 个
· 🔗 链接 **vLLM 서빙 튜토리얼**
https://vllm.readthedocs.io/en/latest/
📁 `links/2026-07-06_vLLM 서빙 튜토리얼.md`
```
**场景 3: "我有多少个想法？"**
```text
"내 아이디어 몇 개야?"
→ 📊 想法盒状态
📁 总共 145 个
🥇 S 等级: 0 个
🥈 A 等级: 1 个
🥉 B 等级: 0 个
⚪ C 等级: 0 个
**最近添加的 5 个：**
· 🧠 [最近添加的想法标题 1]
· 📋 [最近添加的想法标题 2]
· 📰 [最近添加的想法标题 3]
· …
```
### `search_ideas(keyword, limit=5)`
按关键词搜索 idea-box 文件，返回标题、摘要、等级（S/A/B/C）和文件路径。
### `count_ideas()`
返回总数、等级分布（S/A/B/C）和最近 5 个添加的内容。
### `search_memos(keyword="", category="", limit=10)`
搜索 memo-box。可选类别过滤：
`links` · `news` · `quotes` · `references` · `snippets` · `specs` · `tips` · `misc`
### `count_memos()`
返回总数、按类别分类和最近 3 个添加的内容。
### `add_memo(title, content, category="", tags="")`
添加新备忘录。如果 `category` 为空，服务器会自动检测：
- URL → `links`
- 代码/命令/配置 → `snippets`
- 引文/引用文本 → `quotes`
- 新闻关键词 → `news`
- 规格/需求 → `specs`
- 操作方法/错误修复 → `tips`
- 论文/书籍/链接 → `references`
- 默认 → `misc`
返回文件路径和检测到的类别。
## 🚀 快速开始
### 安装
```bash
pip install idea-box-mcp
```
或从源代码安装：
```bash
git clone https://github.com/nerin81-netizen/idea-box-mcp
cd idea-box-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
### 配置路径
默认情况下，服务器读取：
- Idea-box: `~/ideas-h/`
- Memo-box: `~/memos-h/`
要自定义，请编辑 `server.py` 文件顶部的常量：
```python
IDEA_DIR = Path("/your/path/ideas-h")
MEMO_DIR = Path("/your/path/memos-h")
```
### 注册您的 MCP 客户端
#### Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"idea-box": {
"command": "idea-box-mcp"
}
}
}
```
#### Cursor / Cline
`.cursor/mcp.json`:
```json
{
"mcpServers": {
"idea-box": {
"command": "idea-box-mcp"
}
}
}
```
## 🎬 演示
### 搜索想法
```text
👤 AI 相关想法 찾아줘
🤖 Claude:
🔍 'AI' 搜索结果 — 139 个 / 总共 145 个
· **心情成长日记**
每天写简单日记，感受心情成长的应用程序...
📁 `2026-06-28_心情成长日记.md`
· **口袋黑盒**
手机在口袋中连续录音的黑盒...
📁 `2026-06-28_口袋黑盒.md`
```
### 想法盒统计
```text
👤 내 아이디어 몇 개야?
🤖 Claude:
📊 **想法盒状态**
📁 总共 145 个
🥇 S 等级: 0 个
🥈 A 等级: 1 个
🥉 B 等级: 0 个
⚪ C 等级: 0 个
**最近添加的 5 个：**
· 🧠 [最近添加的想法标题 1]
· 📋 [最近添加的想法标题 2]
· 📰 [最近添加的想法标题 3]
· …
```
（实际标题取决于您的本地 `~/ideas-h/` 目录内容。）
### 搜索备忘录
```text
👤 메모박스 통계
🤖 Claude:
📊 **备忘录状态** — 总共 11 个
💬 引语/句子: 7 个
🔗 链接: 2 个
📦 其他: 1 个
🛠️ 小贴士/工作流程: 1 个
```
### 添加备忘录
```text
👤 메모해 — GitHub PAT 安全 push 模式
export GH_TOKEN=YOUR_TOKEN && git push 后 git remote set-url 消毒。
https://github.com/settings/tokens 中撤销。
标签: github, security, mcp-publish
🤖 Claude:
✅ 保存完成: `links/2026-07-06_GitHub PAT 安全 push 模式.md`
类别: 🔗 链接
```
## 🏗 架构
```
┌─────────────────┐ stdio/JSON-RPC ┌──────────────────────┐
│ LLM 客户端 │ ◀──────────────────────▶ │ idea-box-mcp │
│ (Claude/Cursor) │ │ (FastMCP 服务器) │
└─────────────────┘ └──────────┬───────────┘
│ pathlib
┌───────────┴────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ ~/ideas-h/ │ │ ~/memos-h/ │
│ *.md 文件 │ │ 8 个子目录 │
└──────────────┘ └──────────────┘
```
**关键设计选择：
- **stdio 传输** — MCP 标准
- **FastMCP** — Anthropic 的官方 Python SDK
- **零外部依赖** — 纯文件 I/O
- **只读 idea-box** （保留您的结构）+ **写入 memo-box** （添加新文件）
- **自动分类** 备忘录使用简单启发式（URL / 代码 / 关键词）
## 🧪 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 直接测试 stdio JSON-RPC
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | idea-box-mcp
# 测试分类逻辑
python -c "
from idea_box_mcp.server import _detect_memo_category
print(_detect_memo_category('GitHub PAT', 'export GH_TOKEN=...'))
# → 'links'
print(_detect_memo_category('Bash script', 'pip install mcp'))
# → 'snippets'
"
```
## 🌍 路线图
- [x] v0.1.0 — 5 个工具，stdio，idea-box + memo-box
- [ ] v0.2.0 — `add_idea` 工具，带有状态/等级提示
- [ ] v0.3.0 — 备忘录 `tag` 过滤和交叉搜索
- [ ] v0.4.0 — 想法状态转换（💭 → 🔍 → 💼）
- [ ] v0.5.0 — 通过环境变量配置目录
## 🤝 贡献
欢迎提出问题和 PR。特别是：
- 📂 新的备忘录类别
- 🔍 更好的搜索（例如模糊匹配，语义搜索）
- 📝 想法盒写入工具（谨慎 — 保留用户结构）
- 🏷️ 标签分类法
## 📜 许可证
MIT
## 🙏 鸣谢
- 使用 [Anthropic MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- 灵感来自 "本地 Markdown 保险库" 模式
- 参考实现： [arxiv-daily-mcp](https://github.com/nerin81-netizen/arxiv-daily-mcp)
---
> 🌟 如果这个 MCP 帮助您管理本地知识库，请给仓库点赞。
