Medical Knowledge MCP Server

MCP (Model Context Protocol) server cho Medical Knowledge Base với tính năng theo dõi file real-time.

Tổng quan

Server này cho phép Claude Desktop kết nối với knowledge base y tế cục bộ (99+ markdown files) và tương tác như thể bạn đang sử dụng Claude Projects với Files.

Đặc điểm chính

✅ Auto-loading Knowledge Map - Claude tự động "biết" nội dung toàn bộ knowledge base ✅ Real-time File Watching - Tự động phát hiện files mới trong 2 giây ✅ 6 Smart Tools - File access, search, health scoring, SMART cards, care plans, refresh ✅ 3 Reusable Prompts - Templates cho workflows phổ biến ✅ Zero Maintenance - Không cần manual refresh khi thêm files mới

Knowledge Base Structure

MD-Knowledge-Base/
├── CMO - HEALTH OVERVIEW (31 files)
│   ├── Scoring framework với 150 parameters
│   ├── 24-cell health matrix (8 systems × 3 domains)
│   └── Health dashboard specifications
├── CMO - PERFORMANCE MEDICINE (20 files)
│   ├── 13 integrated medical domains
│   ├── Care planning methodology
│   └── Life stage templates
└── CMO - SMART SYSTEM (48 files)
    ├── ~580 medical cards (medications, labs, imaging)
    └── ~391 behavioral cards (nutrition, movement, recovery)

---

Cài đặt

Yêu cầu

• Node.js 20+ (Download)
• Claude Desktop (Download)
• Windows/macOS/Linux

Bước 1: Cài đặt Dependencies

Mở terminal trong thư mục medical-knowledge-mcp:

npm install

Dependencies sẽ được cài:

• @modelcontextprotocol/sdk - MCP SDK chính thức
• chokidar - File system watcher
• zod - Schema validation
• typescript - TypeScript compiler

Bước 2: Build Project

npm run build

Lệnh này sẽ compile TypeScript sang JavaScript trong folder build/.

Bước 3: Kiểm tra Build

Sau khi build, cấu trúc folder sẽ như sau:

medical-knowledge-mcp/
├── build/           # ✓ Compiled JavaScript
├── src/             # TypeScript source
├── package.json
└── tsconfig.json

---

Cấu hình Claude Desktop

Tìm file cấu hình

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Thêm cấu hình MCP

Mở file claude_desktop_config.json (tạo mới nếu chưa có) và thêm:

{
  "mcpServers": {
    "medical-knowledge": {
      "command": "node",
      "args": [
        "d:\\Compass_Coding\\MD Knowledge Base\\medical-knowledge-mcp\\build\\index.js"
      ],
      "env": {
        "KNOWLEDGE_BASE_PATH": "d:\\Compass_Coding\\MD Knowledge Base\\MD-Knowledge-Base"
      }
    }
  }
}

⚠️ Quan trọng: Thay đổi đường dẫn cho phù hợp với máy bạn!

Khởi động lại Claude Desktop

1. Thoát hoàn toàn Claude Desktop (không chỉ đóng cửa sổ)
2. Khởi động lại Claude Desktop
3. Chờ vài giây để MCP server kết nối
4. Kiểm tra icon MCP ở góc dưới bên phải (hình búa nhỏ 🔨)
5. Click icon để xem MCP servers đang chạy

Cấp quyền (lần đầu)

Claude Desktop sẽ hiển thị dialog yêu cầu permission:

• ✓ Approve permission để MCP server có thể truy cập files

---

Cách sử dụng

Trải nghiệm tự nhiên (giống Claude Projects)

Sau khi kết nối, bạn có thể hỏi Claude trực tiếp mà không cần yêu cầu search:

✅ Tốt:

"Giải thích cách tính composite health score"

❌ Không cần:

"Search for composite health score trong knowledge base"

Claude sẽ tự động biết có gì trong knowledge base và trả lời ngay.

Các câu hỏi ví dụ

1. Tổng quan Knowledge Base

"Có bao nhiêu files trong knowledge base?"
"Liệt kê tất cả files trong CMO - HEALTH OVERVIEW"
"Tóm tắt nội dung 3 folders chính"

2. Hỏi về Health Scoring Framework

"Giải thích 24-cell health matrix"
"Cách tính điểm cho cardiovascular system"
"150 MVP parameters là gì?"

3. SMART Cards

"Có những SMART cards nào cho bệnh nhân đái tháo đường?"
"Liệt kê behavioral cards về dinh dưỡng"
"Giải thích sự khác biệt giữa medical cards và behavioral cards"

4. Performance Medicine

"Giải thích Capacity, Resilience, Flexibility"
"13 medical domains là gì?"
"Care plan template cho người lớn tuổi"

5. Sử dụng Tools (khi cần)

Tools sẽ được Claude tự động gọi, nhưng bạn cũng có thể yêu cầu explicitly:

Calculate Health Score:

"Tính điểm sức khỏe cho các thông số sau:
- HbA1c: 7.2
- SBP: 140
- DBP: 90
- LDL: 130
- HDL: 45"

Recommend SMART Cards:

"Gợi ý SMART cards cho bệnh nhân cao huyết áp"

Generate Care Plan:

"Tạo care plan cho bệnh nhân:
- Tuổi: 65
- Bệnh: hypertension, type 2 diabetes
- Mục tiêu: giảm cân, kiểm soát đường huyết"

---

Tools Reference

1. get_file_content

Mục đích: Đọc toàn bộ nội dung một file cụ thể

Parameters:

• filename (string, required): Tên file (vd: "PROJECT_ARCHITECTURE.md")
• folder (string, optional): Folder để thu hẹp tìm kiếm

Ví dụ:

"Đọc file COMPOSITE_SCORING_v2.md"

2. search_files

Mục đích: Tìm kiếm keyword trong tất cả files

Parameters:

• query (string, required): Từ khóa tìm kiếm
• folder (enum, optional): "all" | "CMO - HEALTH OVERVIEW" | ...
• maxResults (number, optional): Số kết quả tối đa (default: 10)

Ví dụ:

"Tìm tất cả thông tin về 'z-score normalization'"

3. calculate_health_score

Mục đích: Tính điểm sức khỏe theo framework

Parameters:

• parameters (array, required): Danh sách parameters với name, value, unit
• patientAge (number, optional): Tuổi bệnh nhân
• patientSex (enum, optional): "M" | "F"
• lifestyleScore (number, optional): Điểm lifestyle 0-100

Output:

• Composite score (0-100)
• System scores breakdown
• Parameter normalization details
• Interpretation

4. recommend_smart_cards

Mục đích: Gợi ý SMART cards cho một condition

Parameters:

• condition (string, required): Tình trạng bệnh hoặc mục tiêu
• cardTypes (array, optional): Filter theo loại card
• maxCards (number, optional): Số cards tối đa (default: 10)

Loại cards:

• Medical: medication, lab, imaging, procedure, referral
• Behavioral: nutrition, movement, recovery, mind-body, micro-learning

5. generate_care_plan

Mục đích: Tạo care plan cá nhân hóa

Parameters:

• patientAge (number, required): Tuổi bệnh nhân
• conditions (array, required): Danh sách bệnh
• goals (array, required): Mục tiêu sức khỏe
• lifeStage (enum, optional): "child" | "adolescent" | "adult" | "elder"

Output:

• Comprehensive care plan với Performance Medicine framework
• Life stage considerations
• Condition management protocols
• SMART card recommendations
• Monitoring schedule

6. refresh_knowledge_base

Mục đích: Manual refresh (backup, thường không cần)

Parameters: Không có

Khi nào dùng:

• File watcher bị tắt
• Cần force refresh ngay lập tức
• Debugging

---

Prompts Reference

1. explain_health_system

Mục đích: Giải thích chi tiết một health system

Arguments:

• system: cardiovascular | neurological | respiratory | metabolic | renal | musculoskeletal | immune | reproductive

Ví dụ:

/prompt explain_health_system system=cardiovascular

2. analyze_parameters

Mục đích: Phân tích health parameters chi tiết

Arguments:

• parameters: Danh sách parameters (required)
• age: Tuổi bệnh nhân (optional)

Ví dụ:

/prompt analyze_parameters parameters="HbA1c: 7.2, SBP: 140" age="55"

3. manage_condition

Mục đích: Comprehensive condition management

Arguments:

• condition: Tên bệnh (required)
• patient_age: Tuổi (optional)

Ví dụ:

/prompt manage_condition condition="type 2 diabetes" patient_age="60"

---

Real-time File Watching

Cách hoạt động

MCP server sử dụng chokidar để theo dõi 3 folders:

• Mỗi khi có file .md mới được thêm/sửa/xóa
• Server tự động refresh knowledge map sau 2 giây (debounce)
• Claude Desktop được notify về changes
• Bạn tiếp tục chat bình thường, Claude đã biết files mới

Test file watching

Bước 1: Đang chat với Claude

Bước 2: Tạo file mới

echo "# Test File" > "MD-Knowledge-Base/CMO - HEALTH OVERVIEW/TEST.md"

Bước 3: Đợi 2 giây

Bước 4: Hỏi Claude

"Có file TEST.md trong knowledge base không?"

Kết quả: Claude sẽ trả lời "Có" và có thể đọc file đó.

Tắt file watching

Nếu muốn tắt (chỉ auto-scan on startup):

Edit src/config.ts:

watchEnabled: false

Rebuild:

npm run build

---

Development

Development Mode (với hot reload)

npm run dev

Sử dụng tsx để chạy TypeScript trực tiếp với watching.

Testing với MCP Inspector

MCP Inspector là visual debugger cho MCP servers:

npm run inspector

Mở browser tại URL được hiển thị để:

• Test từng tool riêng lẻ
• Inspect resources
• View logs real-time
• Debug errors

Build

npm run build

Logs

Logs được ghi ra stderr (hiển thị trong Claude Desktop logs):

• Startup logs
• File scanning progress
• File watcher events
• Tool execution logs
• Errors

Xem logs trên Windows:

%APPDATA%\Claude\logs\

---

Troubleshooting

1. MCP Server không kết nối

Kiểm tra:

• ✓ Đã build project? (npm run build)
• ✓ Đường dẫn trong claude_desktop_config.json đúng chưa?
• ✓ Đã restart Claude Desktop hoàn toàn?
• ✓ Icon MCP có hiển thị không? (góc dưới phải)

Fix:

# Re-build
npm run build

# Kiểm tra build output
ls build/index.js

# Test server manually
node build/index.js

2. Knowledge base không được scan

Kiểm tra:

• ✓ Biến KNOWLEDGE_BASE_PATH trong config đúng không?
• ✓ 3 folders tồn tại không?
• ✓ Có files .md trong folders không?

Fix:

# Test path
ls "d:\Compass_Coding\MD Knowledge Base\MD-Knowledge-Base"

3. File watching không hoạt động

Kiểm tra:

• ✓ watchEnabled: true trong src/config.ts?
• ✓ Đã rebuild sau khi thay đổi config?

Manual refresh:

"Refresh knowledge base"

4. Tool calls fail

Kiểm tra logs:

• Xem errors trong Claude Desktop logs
• Check tool parameters có đúng schema không

Common issues:

• Invalid JSON format trong parameters
• Missing required fields
• Type mismatch (string vs number)

5. Performance chậm

Giải pháp:

• Giảm summaryMaxWords trong config
• Tăng watchDebounce (giảm refresh frequency)
• Disable file watching nếu không cần

---

Configuration Options

src/config.ts

export const config = {
  knowledgeBase: {
    path: process.env.KNOWLEDGE_BASE_PATH || '...',  // Base path
    folders: ['CMO - HEALTH OVERVIEW', ...],          // Folders to scan
    watchEnabled: true,                                // Enable file watching
    watchDebounce: 2000,                               // Debounce time (ms)
    watchIgnore: [...],                                // Patterns to ignore
    cacheEnabled: true,                                // Enable caching
    summaryMaxWords: 200,                              // Summary length
    logFile: './mcp-server.log',                       // Log file
    verboseLogging: false                              // Verbose mode
  },

  server: {
    name: 'medical-knowledge-mcp-server',
    version: '1.0.0'
  },

  healthScoring: {
    systemWeights: { ... },    // System criticality weights
    domainWeights: { ... },    // Structure/Function/Risk weights
    compositeWeights: { ... }  // Objective/Subjective split
  }
};

Environment Variables

Trong claude_desktop_config.json:

"env": {
  "KNOWLEDGE_BASE_PATH": "your/custom/path",
  "NODE_ENV": "production"
}

---

Architecture

High-level Overview

Claude Desktop
    ↓ (stdio transport)
MCP Server (index.ts)
    ↓
Knowledge Manager ← File Watcher (chokidar)
    ↓
├─ Resources (knowledge map + 99 files)
├─ Tools (6 smart tools)
└─ Prompts (3 templates)

Key Components

1. Knowledge Manager (src/core/knowledge-manager.ts)

• Scans folders on startup
• Generates knowledge map
• Caches file metadata
• Provides file access API

2. File Watcher (src/core/file-watcher.ts)

• Watches 3 folders with chokidar
• Debounces changes (2 seconds)
• Triggers knowledge manager refresh
• Notifies server of updates

3. Resources (src/resources/)

• knowledge-map: Auto-loaded index
• Individual files: On-demand access

4. Tools (src/tools/)

• File operations (get, search)
• Health calculations
• SMART card recommendations
• Care plan generation

5. Utilities (src/utils/)

• File scanning
• Search engine
• Health calculator
• Markdown parsing

---

Contributing

Adding New Tools

1. Create tool file: src/tools/your-tool.ts

export const yourToolSchema = z.object({ ... });
export async function handleYourTool(args, manager) { ... }

2. Register in src/index.ts:

import { yourToolSchema, handleYourTool } from './tools/your-tool.js';

// In ListToolsRequestSchema handler
{ name: 'your_tool', inputSchema: yourToolSchema }

// In CallToolRequestSchema handler
case 'your_tool':
  return await handleYourTool(...);

3. Rebuild:

npm run build

Adding New Prompts

Edit src/prompts/medical-prompts.ts:

{
  name: 'your_prompt',
  description: '...',
  arguments: [...]
}

// Add generator function
function generateYourPrompt(args) { ... }

---

License

MIT

---

Support

Issues: Report bugs tại GitHub Issues

Documentation: MCP Official Docs

Community: Claude Discord

---

Version History

v1.0.0 (2025-11-25)

• ✨ Initial release
• ✅ Auto-loading knowledge map
• ✅ Real-time file watching
• ✅ 6 smart tools
• ✅ 3 reusable prompts
• ✅ Comprehensive documentation

---

Built with ❤️ for Medical Knowledge Management