Knowledge MCP Server

MCP server biến GitHub repository thành bộ não cá nhân cho AI. Claude đọc/ghi trực tiếp vào các file markdown trên GitHub thông qua giao thức MCP.

Claude (LLM) ◄──stdio──► MCP Server ◄──HTTPS──► GitHub API ◄──► brain/ repo

Nguyên tắc: MCP server chỉ xử lý dữ liệu, không gọi LLM. Toàn bộ suy luận do Claude đảm nhận.

Mới dùng? Xem GUIDE.md — hướng dẫn chat với AI agent hiệu quả.

Cài đặt nhanh

Yêu cầu

Node.js >= 18
GitHub account + Personal Access Token (tạo tại đây — cần quyền repo)

Cách 1: curl (nhanh nhất)

curl -fsSL https://raw.githubusercontent.com/webcake-tech/knowledge_mcp/main/install-curl.sh | bash

1 lệnh duy nhất — clone, install, build, cấu hình .env interactive, in ra config cho Claude.

Cách 2: clone + install script

git clone https://github.com/webcake-tech/knowledge_mcp.git
cd knowledge_mcp
./install.sh

Cách 3: thủ công

git clone https://github.com/webcake-tech/knowledge_mcp.git
cd knowledge_mcp
npm install
npm run build
cp .env.example .env
# Edit .env với token + repo info

Cập nhật

./update.sh

Script sẽ tự động:

Pull code mới nhất
Cài lại dependencies nếu có thay đổi
Rebuild TypeScript
Kiểm tra có biến môi trường mới nào cần thêm vào .env

Cấu hình `.env`

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx   # Bắt buộc
GITHUB_OWNER=yourusername               # Bắt buộc
GITHUB_REPO=brain                       # Bắt buộc
GITHUB_BRANCH=main                      # Mặc định: main
BRAIN_BASE_PATH=brain                   # Mặc định: brain
LOG_LEVEL=info                          # debug | info | warn | error
CACHE_TTL_MS=30000                      # Cache reads (ms)
WRITE_RETRIES=3                         # Retry khi conflict

Kết nối với AI Platform

MCP server chạy qua stdio — tương thích mọi platform hỗ trợ MCP.

Thay /path/to/knowledge_mcp bằng đường dẫn thực tế. Script install.sh sẽ in ra đường dẫn chính xác.

Claude Desktop

File cấu hình:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/path/to/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add knowledge-brain -- node /path/to/knowledge_mcp/dist/index.js

Cursor

Settings → MCP Servers → Add new:

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/path/to/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

VS Code (Copilot / Roo Code / Continue)

File .vscode/mcp.json trong project hoặc global settings:

{
  "servers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/path/to/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

Windsurf

File ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/path/to/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

OpenAI Codex CLI

File ~/.codex/config.json:

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/path/to/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

Antigravity

Project settings → Integrations → MCP → Add server:

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/path/to/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

Bất kỳ MCP Client nào

Cấu hình chung — chỉ cần 3 thứ:

Field	Value
Command	`node`
Args	`/path/to/knowledge_mcp/dist/index.js`
Env	`GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO`

Transport: stdio (mặc định).

Bắt đầu sử dụng

Lần đầu — tạo repo rỗng trên GitHub, rồi nói:

Khởi tạo brain cho tôi

Claude tạo toàn bộ cấu trúc trong 1 commit:

brain/
├── inbox/capture.md
├── tasks/today.md, backlog.md
├── notes/ideas.md, learning.md
├── goals/short-term.md, long-term.md
└── knowledge/general.md

Sau đó — nói chuyện tự nhiên:

"Hôm nay tôi cần làm gì?"          → getTodayTasks
"Thêm task: thiết kế landing page"  → addTask
"Xong task review PR rồi"           → markTaskDone
"Tóm tắt goals của tôi"            → getGoals
"Ghi lại ý tưởng: AI chatbot"      → addNote / saveToInbox

Danh sách Tools (15)

Khởi tạo

Tool	Mô tả
`initBrain`	Tạo toàn bộ cấu trúc brain trên repo rỗng (1 commit)

Tasks

Tool	Input	Mô tả
`getTasks`	`section` (today/backlog/all)	Lấy tasks
`getTodayTasks`	—	Tasks hôm nay
`getBacklog`	—	Tasks backlog
`addTask`	`text`, `target`	Thêm task
`markTaskDone`	`taskId` hoặc `text`	Đánh dấu xong

Notes / Goals / Inbox

Tool	Input	Mô tả
`getNotes`	`section` (ideas/learning)	Lấy ghi chú
`addNote`	`content`, `file`	Thêm ghi chú
`getGoals`	`section` (short-term/long-term)	Lấy mục tiêu
`getInbox`	—	Lấy inbox
`saveToInbox`	`content`	Lưu nhanh vào inbox

Knowledge Base

Tool	Input	Mô tả
`listTopics`	—	Danh sách topics (name + description + tags)
`getKnowledge`	`topic`	Đọc toàn bộ 1 topic
`addKnowledge`	`topic`, `title`, `content`, `description?`, `tags?`	Thêm kiến thức
`searchKnowledge`	`query`	Tìm kiếm cross-topic (tag → title → content)

Knowledge Base

Lưu trữ kiến thức theo topic trong folder knowledge/. Mỗi file có frontmatter:

---
name: Chính sách bán hàng
description: Quy định đổi trả, bảo hành, hoàn tiền
tags: chính sách, đổi trả, bảo hành
---

## Chính sách đổi trả

- Đổi trả trong vòng 7 ngày...

## Bảo hành

- Sản phẩm điện tử: 12 tháng...

Ví dụ

"Lưu kiến thức Docker: cách tối ưu Dockerfile"  → addKnowledge
"Nhắc lại cách undo commit?"                    → searchKnowledge
"Tôi đã lưu những gì?"                          → listTopics
"Cho tôi xem hết về Docker"                     → getKnowledge
"Chính sách bảo hành thế nào?"                  → searchKnowledge (match tag)

Search ranking

Tag match — "bảo hành" match tag → trả về tất cả entries của topic đó
Title match — match heading ##
Content match — match nội dung

Cấu trúc source code

src/
├── index.ts              # Entry point
├── mcp.ts                # Đăng ký tools
├── config.ts             # Env vars
├── logger.ts             # JSON logger → stderr
├── errors.ts             # Error types
├── core/
│   ├── brain.ts          # Brain facade (tasks, notes, goals, inbox)
│   ├── parser.ts         # Markdown ↔ structured data
│   ├── knowledge.ts      # Knowledge base (frontmatter + search)
│   └── aggregator.ts     # Cross-file queries
├── github/
│   ├── client.ts         # GitHub API (cache + retry)
│   └── sync.ts           # Section → file path mapping
└── tools/
    ├── helpers.ts         # Tool wrapper
    ├── brain.ts           # initBrain
    ├── tasks.ts           # Task tools
    ├── notes.ts           # Note + goal tools
    ├── inbox.ts           # Inbox tools
    └── knowledge.ts       # Knowledge tools

Scripts

Lệnh	Mô tả
`curl ... \| bash`	Cài từ xa 1 lệnh (clone + install + build + config)
`./install.sh`	Cài đặt lần đầu (deps + build + .env)
`./update.sh`	Cập nhật (pull + deps + rebuild + check .env)
`npm run build`	Build TypeScript → `dist/`
`npm run start`	Chạy server production
`npm run dev`	Chạy trực tiếp bằng tsx

Lưu ý kỹ thuật

initBrain dùng Git Tree API — tạo tất cả file trong 1 commit, hoạt động trên repo rỗng
TTL Cache — reads cached 30s, writes tự invalidate
Retry on conflict — ghi file gặp SHA conflict (409) tự retry 3 lần
Format-preserving — sửa task chỉ thay đúng dòng, không rewrite file
CRLF safe — normalize \r\n, hỗ trợ frontmatter, numbered lists, priority (!/!!/!!!), due dates (@due())
Frontmatter knowledge — tags cho phép search nhanh không cần đọc content
Structured logging — JSON logs ra stderr, không ảnh hưởng MCP stdout

License

MIT

Knowledge MCP Server

Knowledge MCP Server

Cài đặt nhanh

Yêu cầu

Cách 1: curl (nhanh nhất)

Cách 2: clone + install script

Cách 3: thủ công

Cập nhật

Cấu hình .env

Kết nối với AI Platform

Claude Desktop

Claude Code (CLI)

Cursor

VS Code (Copilot / Roo Code / Continue)

Windsurf

OpenAI Codex CLI

Antigravity

Bất kỳ MCP Client nào

Bắt đầu sử dụng

Lần đầu — tạo repo rỗng trên GitHub, rồi nói:

Sau đó — nói chuyện tự nhiên:

Danh sách Tools (15)

Khởi tạo

Tasks

Notes / Goals / Inbox

Knowledge Base

Knowledge Base

Ví dụ

Search ranking

Cấu trúc source code

Scripts

Lưu ý kỹ thuật

License

Reviews

Cấu hình `.env`