# 🤖 Notion Agent Hub

> **AI Agent Hub for Notion** — orchestrate AI agents through Notion databases with human-in-the-loop approval. Built with MCP.

<!-- Hero Banner -->
<div align="center">

![Notion](https://img.shields.io/badge/Notion-000000?style=for-the-badge&logo=notion&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-blue?style=for-the-badge)
![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
![Node](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
![CI](https://img.shields.io/badge/CI-GitHub_Actions-2088FF?style=for-the-badge&logo=githubactions&logoColor=white)

**Turn your Notion workspace into an AI command center.**

[Quick Start](#-quick-start) · [Architecture](#-architecture) · [Tools](#-tools) · [Agents](#-agent-workflows) · [Setup Guide](docs/setup.md)

</div>

---

## ✨ What It Does

Notion Agent Hub is an **MCP (Model Context Protocol) server** that connects AI assistants (Claude, GPT, etc.) to your Notion workspace. It provides:

1. **🔍 Research Agent** — Search the web, compile findings, and write structured research pages to Notion
2. **🔄 GitHub Tracker** — Monitor GitHub PRs and sync their status to a Notion database
3. **📝 Content Pipeline** — Read outlines from Notion, generate drafts, and submit for human review

All tasks flow through a **Notion-native task queue** with human-in-the-loop approval — you stay in control.

## 🏗 Architecture

```mermaid
graph TB
    subgraph "AI Assistant"
        C[Claude / GPT / etc.]
    end

    subgraph "MCP Server — notion-agent-hub"
        direction TB
        S[Server Entry Point]

        subgraph "Tools Layer"
            NR[📖 notion-read]
            NW[✏️ notion-write]
            NQ[🔎 notion-query]
            WS[🌐 web-search]
            CR[💻 code-run]
        end

        subgraph "Agent Layer"
            RA[🔬 Research]
            GT[🔄 GitHub Tracker]
            CP[📝 Content Pipeline]
        end

        TQ[📋 Task Queue]
    end

    subgraph "Your Notion Workspace"
        TD[(Task Database)]
        RP[Research Pages]
        DP[Draft Pages]
        PR[(PR Tracker DB)]
    end

    C <-->|MCP Protocol| S
    S --> NR & NW & NQ & WS & CR
    TQ -->|Poll| TD
    RA -->|Write| RP
    GT -->|Sync| PR
    CP -->|Write| DP
    TD -->|Human creates tasks| TQ
```

For a deeper dive, see [docs/architecture.md](docs/architecture.md).

## 📁 Project Structure

```
notion-agent-hub/
├── .github/
│   └── workflows/
│       └── ci.yml              # CI: type-check + tests (Node 22)
├── docs/
│   ├── architecture.md         # System architecture & data flow
│   ├── setup.md                # Detailed setup guide
│   └── images/                 # Diagrams
├── scripts/                    # Standalone agent test scripts
│   ├── test-research.ts
│   ├── test-github-tracker.ts
│   └── test-content-pipeline.ts
├── src/
│   ├── index.ts                # MCP server entry point (stdio)
│   ├── agents/                 # Higher-level agent workflows
│   │   ├── research.ts
│   │   ├── github-tracker.ts
│   │   └── content-pipeline.ts
│   ├── queue/
│   │   └── task-queue.ts       # Notion-native human-in-the-loop queue
│   ├── tools/                  # MCP tool implementations
│   │   ├── notion-read.ts
│   │   ├── notion-write.ts
│   │   ├── notion-query.ts
│   │   ├── web-search.ts
│   │   └── code-run.ts
│   └── utils/
│       ├── notion-client.ts    # Shared Notion API client
│       └── logger.ts
├── tests/                      # Vitest unit tests for tools
├── .env.example                # Environment variable template
├── package.json
├── tsconfig.json
└── LICENSE                     # MIT
```

## 🚀 Quick Start

### Prerequisites

- **Node.js 22+**
- A Notion account with API access
- A Notion integration (API key)

### 1. Clone & Install

```bash
git clone https://github.com/girishlade111/notion-agent-hub.git
cd notion-agent-hub
npm install
```

### 2. Configure

```bash
cp .env.example .env
```

Edit `.env` with your keys:

```env
NOTION_API_KEY=ntn_your_integration_secret
NOTION_DATABASE_ID=your_task_database_id
OPENAI_API_KEY=sk-your_openai_key  # Optional
```

> 📖 See the [Setup Guide](docs/setup.md) for detailed instructions on creating a Notion integration and task database.

### 3. Build & Run

```bash
npm run build
npm start
```

### 4. Connect to Claude Desktop

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "notion-agent-hub": {
      "command": "node",
      "args": ["/path/to/notion-agent-hub/dist/index.js"],
      "env": {
        "NOTION_API_KEY": "ntn_your_key",
        "NOTION_DATABASE_ID": "your_db_id"
      }
    }
  }
}
```

## 🛠 Tools

### `notion-read`

Read pages, databases, and blocks from Notion.

```
Input:  { page_id?: string, database_id?: string, block_id?: string }
Output: Page content with properties and child blocks
```

### `notion-write`

Create or update Notion pages with rich content.

```
Input:  { action: "create" | "update" | "append", parent_id?, page_id?, title?, blocks? }
Output: { id, url, created/updated/appended: true }
```

Supported block types: `paragraph`, `heading_1/2/3`, `bulleted_list_item`, `numbered_list_item`, `toggle`, `quote`, `callout`, `divider`, `code`

### `notion-query`

Query databases with filters and sorting.

```
Input:  { database_id, filter?, sorts?, page_size? }
Output: { results: [...pages], has_more, next_cursor }
```

### `web-search`

Search the web using Brave Search (or DuckDuckGo fallback).

```
Input:  { query: string, count?: number }
Output: { results: [{ title, url, snippet }], source }
```

### `code-run`

Execute JavaScript in a sandboxed environment (Node.js vm module).

```
Input:  { code: string, timeout_ms?: number }
Output: { success, result?, stdout, stderr }
```

## 🤖 Agent Workflows

### 🔬 Research Agent

**Input:** Topic + parent page ID
**Process:** Web search → compile sources → create structured Notion page
**Output:** Research page with sources, findings, and review checklist

### 🔄 GitHub Tracker

**Input:** GitHub repo + Notion database ID
**Process:** Fetch PRs → compare with existing entries → create/update pages
**Output:** Synced PR database in Notion

### 📝 Content Pipeline

**Input:** Outline page ID + parent page ID
**Process:** Read outline → (optional research) → generate draft → create page
**Output:** Draft page with review checklist, ready for human editing

## 🔄 Human-in-the-Loop

The task queue uses your Notion database as the control plane:

```
You create a task          →  Status: Pending
Agent picks it up          →  Status: Running
Agent writes results       →  Status: Done ✅
Something went wrong?      →  Status: Failed ❌ (with error details)
```

**You're always in control.** Tasks only run when you create them. Results are always written back to Notion for your review.

### Task Database Schema

| Property | Type   | Description                     |
|----------|--------|---------------------------------|
| Name     | Title  | Task description                |
| Status   | Status | Pending → Running → Done/Failed |
| Type     | Select | research / github-tracker / content-pipeline |
| Input    | Text   | JSON input parameters           |
| Output   | Text   | JSON results                    |
| Error    | Text   | Error message (if failed)       |

## 🧰 Tech Stack

| Layer      | Technology |
|------------|------------|
| Language   | TypeScript (ESM, strict) |
| Runtime    | Node.js 22+ |
| Protocol   | Model Context Protocol (`@modelcontextprotocol/sdk`) |
| Notion API | `@notionhq/client` |
| Validation | Zod |
| AI (optional) | OpenAI SDK |
| Tests      | Vitest |
| CI         | GitHub Actions |

## 🧪 Development

```bash
# Run tests
npm test

# Watch mode
npm run test:watch

# Type checking
npm run lint

# Build
npm run build

# Dev mode (watch + rebuild)
npm run dev
```

### Available Scripts

| Script          | Description                        |
|-----------------|------------------------------------|
| `npm run build` | Compile TypeScript to `dist/`      |
| `npm run dev`   | Type-check in watch mode           |
| `npm start`     | Run the compiled MCP server        |
| `npm test`      | Run Vitest suite once              |
| `npm run test:watch` | Run Vitest in watch mode      |
| `npm run lint`  | TypeScript type-check (`--noEmit`) |

### CI

Every push and pull request to `main` runs `.github/workflows/ci.yml`:

1. Install dependencies (`npm ci`)
2. TypeScript compile check (`tsc --noEmit`)
3. Run tests (`npm test`)

## 🔐 Environment Variables

| Variable            | Required | Description                              |
|---------------------|----------|------------------------------------------|
| `NOTION_API_KEY`    | ✅ Yes   | Notion internal integration secret (`ntn_…`) |
| `NOTION_DATABASE_ID`| ✅ Yes   | Task database ID                         |
| `OPENAI_API_KEY`    | ❌ No    | Enables AI content generation            |

Never commit `.env` — it is gitignored. Use `.env.example` as a template.

## ❓ Troubleshooting

| Issue | Fix |
|-------|-----|
| `Unauthorized` from Notion | Verify `NOTION_API_KEY` and that the integration is connected to the page/database (⋯ → Connections) |
| Empty query results | Check `NOTION_DATABASE_ID` and database permissions |
| MCP server not showing in Claude | Ensure `npm run build` was run and the path in config points to `dist/index.js` |
| Type errors after changes | Run `npm install` then `npm run lint` |

## 📸 Demo

<!-- TODO: Add demo GIF showing the workflow -->
![Demo](docs/demo.gif)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m "Add amazing feature"`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please ensure `npm run lint` and `npm test` pass before submitting.

## 📜 License

MIT — see [LICENSE](LICENSE).

---

<div align="center">

**Built for the [Notion MCP Challenge](https://notion.so)** 🏆

Powered by [Model Context Protocol](https://modelcontextprotocol.io)

</div>