#  mcp-notes-server

**Repository Path**: zlaxx/mcp-notes-server

## Basic Information

- **Project Name**:  mcp-notes-server
- **Description**: 知识库管理MCP
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Notes Server

一个本地知识库系统，由两个独立模块组成：

- **MCP Server**：接入 Claude Desktop / Cursor，让大模型直接读写知识库
- **Web UI**：本地可视化管理界面，支持手动导入文档、Markdown 渲染与多主题阅读

---

## 架构概览

```text
┌─────────────────────────────────────────────────────────────┐
│                        用户                                  │
│            │                         │                       │
│     Claude Desktop               浏览器 :3000               │
│     (Cursor / API)               (Web 管理界面)              │
└────────────┼─────────────────────────┼───────────────────────┘
             │                         │
             │ stdio (JSON-RPC)         │ HTTP REST
             ▼                         ▼
┌────────────────────┐    ┌────────────────────────┐
│   src/index.ts     │    │    src/web.ts           │
│   MCP Server       │    │    HTTP Server :3000    │
│                    │    │                         │
│  Tools:            │    │  GET  /api/notes        │
│  · create_note     │    │  POST /api/notes        │
│  · search_notes    │    │  GET  /api/notes/:id    │
│  · delete_note     │    │  DELETE /api/notes/:id  │
│  · read_note       │    │                         │
│  · list_md_docs    │    │  GET  /*  → web/dist/   │
│  · save_summary    │    │  (Vite 构建产物)         │
│                    │    └────────────┬───────────┘
│  Resources:        │                 │
│  · notes://all     │                 │ 开发时由 Vite
│  · notes://{id}    │                 │ dev server 接管
│                    │    ┌────────────▼───────────┐
│  Prompts:          │    │    web/ (React 前端)    │
│  · summarize_notes │    │    Vite + TypeScript    │
│                    │    │    Tailwind CSS         │
└────────────┬───────┘    │    TanStack Query       │
             │            └────────────────────────┘
             └──────────────────┐
                                ▼
                  ┌─────────────────────────┐
                  │   NoteStore             │
                  │   storage/notes/*.md    │
                  │                         │
                  │  每条笔记 = 一个 .md 文件 │
                  │  YAML front-matter      │
                  │  + Markdown 正文        │
                  └─────────────────────────┘
```

### 两个进程完全独立

| 进程 | 入口 | 通信协议 | 用途 |
| ---- | ---- | ------- | ---- |
| MCP Server | `src/index.ts` | stdio JSON-RPC | Claude Desktop / Cursor 调用 |
| HTTP Server | `src/web.ts` | HTTP REST | Web 管理界面 + 浏览器访问 |

两者**共享同一份** `storage/notes/` 文件目录，数据天然同步，无需额外通信。

---

## 项目结构

```text
mcp-notes-server/
├── src/                          # MCP Server + HTTP Server（TypeScript）
│   ├── index.ts                  # MCP Server 入口，注册所有 Tool/Resource/Prompt
│   ├── web.ts                    # HTTP Server 入口，提供 REST API + serve 前端静态文件
│   ├── store/
│   │   └── note-store.ts         # 数据层：文件读写、序列化/反序列化
│   ├── tools/
│   │   ├── create-note.ts        # Tool: 创建笔记
│   │   ├── search-notes.ts       # Tool: 关键词搜索
│   │   ├── delete-note.ts        # Tool: 删除笔记
│   │   ├── read-note.ts          # Tool: 读取笔记（加载为对话上下文）
│   │   ├── list-md-documents.ts  # Tool: 列出所有文档
│   │   └── save-conversation-summary.ts  # Tool: 压缩当前对话并保存
│   ├── resources/
│   │   └── notes-resource.ts     # Resource: notes://all  notes://{id}
│   └── prompts/
│       └── summarize.ts          # Prompt: summarize_notes 模板
│
├── web/                          # Web 前端（React + Vite）
│   ├── src/
│   │   ├── main.tsx              # 前端入口
│   │   ├── App.tsx               # 根组件，布局与路由状态
│   │   ├── api/notes.ts          # fetch 封装，对接 /api/* 接口
│   │   ├── types/note.ts         # Note 类型定义
│   │   ├── contexts/toast.tsx    # 全局 Toast 通知
│   │   └── components/
│   │       ├── Sidebar.tsx       # 左侧文档列表 + 搜索
│   │       ├── NoteItem.tsx      # 单条文档项（含删除）
│   │       ├── ImportForm.tsx    # 文档导入表单（手动 + 文件上传）
│   │       ├── NoteViewer.tsx    # 文档阅读器（含主题切换）
│   │       └── MarkdownRenderer.tsx  # Markdown 渲染（react-markdown + GFM + 代码高亮）
│   ├── vite.config.ts            # 开发时代理 /api → localhost:3000
│   ├── tailwind.config.js
│   └── package.json
│
├── storage/notes/                # 数据目录（运行时自动创建）
│   └── *.md                      # 每条笔记一个文件
│
├── dist/                         # TypeScript 编译产物
├── package.json
└── tsconfig.json
```

---

## 数据存储格式

每条笔记存为 `storage/notes/<id>.md`：

```markdown
---
id: mo137gffurx16
title: 示例标题
tags: 工作, 重要
createdAt: 2026-04-16T12:34:56.000Z
updatedAt: 2026-04-16T12:34:56.000Z
---

这里是笔记正文（支持 Markdown）。
```

---

## 快速开始

### 安装依赖

```bash
npm install
npm run web:install   # 安装前端依赖
```

### 开发模式

```bash
# 启动 Web 管理界面（API + Vite HMR，一条命令）
npm run web:dev
# 浏览器访问 http://localhost:5173

# 启动 MCP Server（供 Claude Desktop 使用，独立进程）
npm run dev
```

### 生产模式

```bash
npm run build         # 编译 TypeScript
npm run build:web     # 构建前端（生成 web/dist/）

npm run start         # 启动 MCP Server
npm run web:start     # 启动 HTTP Server（同时 serve 前端），访问 http://localhost:3000
```

---

## 接入 Claude Desktop

编译后配置 `claude_desktop_config.json`：

- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["D:/OH_Product/mcp-notes-server/dist/index.js"]
    }
  }
}
```

保存后重启 Claude Desktop 即可使用以下能力：

| Tool | 说明 |
| ---- | ---- |
| `list_md_documents` | 查看知识库中所有文档 |
| `read_note` | 读取指定文档，内容注入当前对话上下文 |
| `create_note` | 创建新笔记 |
| `search_notes` | 关键词搜索 |
| `delete_note` | 删除笔记 |
| `save_conversation_summary` | 将当前对话压缩保存为知识库文档 |

### 典型使用流程

```text
1. list_md_documents          → 查看有哪些经验文档
2. read_note(id)              → 加载某篇文档为当前上下文
3. （基于文档内容展开对话）
4. save_conversation_summary  → 将新产生的内容存回知识库
```

---

## 技术栈

| 层 | 技术 |
| -- | ---- |
| MCP 协议 | `@modelcontextprotocol/sdk` + `StdioServerTransport` |
| HTTP 服务 | Node.js 内置 `http` 模块，无额外框架 |
| 数据层 | 文件系统，Markdown + YAML front-matter |
| 前端构建 | Vite 6 + React 18 + TypeScript |
| 样式 | Tailwind CSS 3 + `@tailwindcss/typography` |
| 数据请求 | TanStack Query v5 |
| Markdown 渲染 | `react-markdown` + `remark-gfm` + `rehype-highlight` |

---

## 调试说明

MCP Server 使用 `StdioServerTransport`，`stdout` 专用于 JSON-RPC 协议数据流。所有日志必须输出到 `stderr`：

```typescript
console.error("调试信息")   // ✅ 正确
console.log("调试信息")     // ❌ 会污染协议流
```