# Notion MCP Server

這是一個 Model Context Protocol (MCP) 伺服器，用於連接和操作 Notion API。它提供了一套完整的工具來讀取、寫入和管理 Notion 頁面與資料庫。

## 功能特色

- 🔍 **搜尋頁面** - 在 Notion 工作區中搜尋頁面
- 📄 **頁面操作** - 取得、建立和更新 Notion 頁面
- 🗃️ **資料庫查詢** - 查詢和操作 Notion 資料庫
- 📋 **內容管理** - 讀取和修改頁面內容區塊
- 🔄 **即時同步** - 透過 MCP 協議即時與 Notion 同步

## 安裝和設定

### 1. 安裝依賴

```bash
npm install
```

### 2. 設定 Notion 整合

1. 前往 [Notion 整合設定頁面](https://www.notion.so/my-integrations)
2. 建立新的整合
3. 複製整合 token
4. 建立 `.env` 檔案並加入您的 token：

```bash
cp .env.example .env
# 編輯 .env 檔案，加入您的 Notion token
```

### 3. 建立專案

```bash
npm run build
```

## 使用方法

### 開發模式

```bash
npm run dev
```

### 生產模式

```bash
npm start
```

### 監控模式（自動重新載入）

```bash
npm run watch
```

## 可用的工具

### 頁面操作

- `get-page` - 根據 ID 取得頁面詳細資訊
- `search-pages` - 搜尋頁面
- `create-page` - 建立新頁面
- `update-page` - 更新頁面屬性

### 資料庫操作

- `query-database` - 查詢資料庫內容

### 資源

- `notion://recent-pages` - 最近存取的頁面
- `notion://databases` - 可存取的資料庫清單

## 在 VS Code 中使用

1. 確保已安裝 MCP 相關的 VS Code 擴充功能
2. 使用 `.vscode/mcp.json` 配置檔案來設定伺服器連接
3. 在 VS Code 中啟動偵錯模式以測試 MCP 伺服器

## API 範例

### 搜尋頁面

```json
{
  "name": "search-pages",
  "arguments": {
    "query": "meeting notes",
    "filter": {
      "property": "Status",
      "value": "Active"
    }
  }
}
```

### 建立頁面

```json
{
  "name": "create-page",
  "arguments": {
    "parent": {
      "database_id": "your-database-id"
    },
    "properties": {
      "Name": {
        "title": [
          {
            "text": {
              "content": "新頁面標題"
            }
          }
        ]
      }
    }
  }
}
```

## 錯誤排除

### 常見問題

1. **Authentication Error**: 確認 `NOTION_TOKEN` 環境變數已正確設定
2. **Permission Error**: 確認 Notion 整合有適當的權限存取所需的頁面和資料庫
3. **Module Resolution Error**: 確認所有依賴已正確安裝

### 偵錯

在開發模式下，伺服器會在 stderr 輸出詳細的偵錯資訊。

## 專案結構

```
.
├── src/
│   ├── index.ts           # MCP 伺服器主程式
│   └── notion-service.ts  # Notion API 服務類別
├── .vscode/
│   └── mcp.json          # VS Code MCP 配置
├── .github/
│   └── copilot-instructions.md  # GitHub Copilot 指令
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

## 授權

MIT License

## 相關連結

- [Model Context Protocol 官方文件](https://modelcontextprotocol.io/)
- [Notion API 文件](https://developers.notion.com/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)