# 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](https://nodejs.org/))
- Claude Desktop ([Download](https://claude.ai/download))
- Windows/macOS/Linux

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

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

```bash
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

```bash
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:

```json
{
  "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
```bash
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`:**
```typescript
watchEnabled: false
```

**Rebuild:**
```bash
npm run build
```

---

## Development

### Development Mode (với hot reload)

```bash
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:

```bash
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

```bash
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:**
```bash
# 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:**
```bash
# 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`

```typescript
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`:**
```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`
```typescript
export const yourToolSchema = z.object({ ... });
export async function handleYourTool(args, manager) { ... }
```

**2. Register in `src/index.ts`:**
```typescript
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:**
```bash
npm run build
```

### Adding New Prompts

**Edit `src/prompts/medical-prompts.ts`:**
```typescript
{
  name: 'your_prompt',
  description: '...',
  arguments: [...]
}

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

---

## License

MIT

---

## Support

**Issues:** Report bugs tại [GitHub Issues](https://github.com/your-repo/issues)

**Documentation:** [MCP Official Docs](https://modelcontextprotocol.io/)

**Community:** [Claude Discord](https://discord.gg/claude)

---

## 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**