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

git clone https://github.com/<your-username>/knowledge_mcp.git
cd knowledge_mcp

npm install

npm run build

cp .env.example .env

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_OWNER=yourusername
GITHUB_REPO=brain
GITHUB_BRANCH=main
BRAIN_BASE_PATH=brain

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

cd example-brain
git init
git add .
git commit -m "init: brain repository"
git remote add origin https://github.com/<your-username>/brain.git
git push -u origin main

- [ ] Task chưa làm
- [x] Task đã hoàn thành
- [ ] !!! Task ưu tiên cao #work @due(2026-03-20)
- [ ] !! Task ưu tiên trung bình #personal

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/đường-dẫn-tuyệt-đối/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain",
        "GITHUB_BRANCH": "main",
        "BRAIN_BASE_PATH": "brain"
      }
    }
  }
}

claude mcp add knowledge-brain -- node /đường-dẫn-tuyệt-đối/knowledge_mcp/dist/index.js

{
  "mcpServers": {
    "knowledge-brain": {
      "command": "node",
      "args": ["/đường-dẫn-tuyệt-đối/knowledge_mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "yourusername",
        "GITHUB_REPO": "brain"
      }
    }
  }
}

"Khởi tạo brain cho tôi"
→ Claude gọi initBrain, tạo toàn bộ cấu trúc

"Hôm nay tôi cần làm gì?"
→ Claude gọi getTodayTasks, phân tích và trả lời

"Thêm task: thiết kế landing page"
→ Claude gọi addTask với text "thiết kế landing page"

"Đánh dấu task review PR là xong"
→ Claude gọi markTaskDone với text "review PR"

"Tóm tắt goals của tôi"
→ Claude gọi getGoals cho cả short-term và long-term

"Ghi lại ý tưởng: xây dựng AI chatbot cho team"
→ Claude gọi saveToInbox hoặc addNote

"Tôi đang làm dự án gì?"
→ Claude gọi getTasks và phân tích context

brain/knowledge/
├── javascript.md     ← topic về JS
├── git.md            ← topic về Git
├── docker.md         ← topic về Docker
└── cooking.md        ← không chỉ code — lưu gì cũng được

# JavaScript

## var vs let vs const

- `var`: function-scoped, hoisted → tránh dùng
- `let`: block-scoped, có thể reassign
- `const`: block-scoped, không thể reassign

## Promise vs async/await

Promise là cách xử lý bất đồng bộ trong JS.
async/await là syntax sugar cho Promise...

User: "Nhắc lại cách undo commit trong git?"

Claude:
  1. searchKnowledge("undo commit")
  2. Tìm thấy entry "Undo last commit" trong topic "git"
  3. Trả lời: git reset --soft HEAD~1

User: "Lưu lại cách tối ưu Dockerfile cho Node.js"

Claude:
  1. addKnowledge("docker", "Dockerfile tối ưu cho Node.js", "FROM node:20-alpine...")
  2. Trả lời: Đã lưu vào topic docker

User: "Ghi nhớ: trứng luộc lòng đào cần đúng 6 phút 30 giây"

Claude:
  1. addKnowledge("cooking", "Trứng luộc lòng đào", "Nước sôi → thả trứng → 6:30 → ngâm đá")
  2. File cooking.md được tạo tự động nếu chưa có

User: "Tôi đã lưu những kiến thức gì?"

Claude:
  1. listTopics()
  2. Trả về: javascript, git, docker, cooking
  → Chỉ 1 API call, không đọc nội dung file nào

User: "Cho tôi xem hết kiến thức về Docker"

Claude:
  1. getKnowledge("docker")
  2. Trả về tất cả entries: Các lệnh cơ bản, Dockerfile tối ưu, Docker Compose...

User: "Tôi có ghi gì về async không?"

Claude:
  1. searchKnowledge("async")
  2. Tìm thấy entry "Promise vs async/await" trong topic "javascript"
  3. Trả về nội dung match

src/
├── index.ts            # Entry point — khởi tạo server + stdio transport
├── mcp.ts              # Đăng ký tất cả MCP tools
├── config.ts           # Load biến môi trường
├── logger.ts           # Structured JSON logger (ghi ra stderr)
├── errors.ts           # Error hierarchy (NotFoundError, ConflictError...)
├── core/
│   ├── brain.ts        # Facade chính — đọc/ghi/init brain qua GitHub
│   ├── parser.ts       # Parse markdown ↔ structured data
│   ├── knowledge.ts    # Knowledge base — lưu/tìm kiến thức theo topic
│   └── aggregator.ts   # Truy vấn cross-file (tổng hợp tasks)
├── github/
│   ├── client.ts       # Octokit wrapper (getFile, updateFile, listDirectory...)
│   └── sync.ts         # Map brain section → GitHub file path + retry
├── tools/
│   ├── helpers.ts      # toolHandler wrapper (error handling + logging)
│   ├── brain.ts        # Tool: initBrain
│   ├── tasks.ts        # Tools: getTasks, addTask, markTaskDone...
│   ├── notes.ts        # Tools: getNotes, addNote, getGoals
│   ├── inbox.ts        # Tools: getInbox, saveToInbox
│   └── knowledge.ts    # Tools: listTopics, getKnowledge, addKnowledge, searchKnowledge
└── types/
    ├── brain.ts        # Types: FileContent, BrainSection, Note, Goal
    └── task.ts         # Types: Task, TaskStatus, TaskPriority

npm run build    # Compile TypeScript → dist/
npm run start    # Chạy server (production)
npm run dev      # Chạy trực tiếp bằng tsx (development)