PersonalDataHub

通过 PersonalDataHub 访问控制网关提取个人数据（电子邮件、问题）并提出出站操作（草稿、回复）。数据在到达代理之前会根据所有者的策略进行过滤、编辑和调整。

# PersonalDataHub

Access personal data from Gmail, GitHub, and other sources through the PersonalDataHub access control gateway. The data owner controls what the agent can see, which fields are visible, what gets redacted, and which actions are allowed.

## MCP Setup (Recommended)

PersonalDataHub provides an MCP server for native tool discovery. Add to your Claude Code config (`.claude/settings.json`):

```json
{
  "mcpServers": {
    "personaldatahub": {
      "command": "npx",
      "args": ["pdh", "mcp"]
    }
  }
}
```

This registers source-specific tools dynamically — only sources with connected OAuth tokens get tools.

## Tools

### read_emails
*(Gmail — requires connected Gmail OAuth)*

Pull emails from Gmail. Data is filtered and redacted according to the owner's access control policy.

**Parameters:**
- `purpose` (required) — Why this data is needed (logged for audit)
- `query` (optional) — Gmail search query (e.g., `"is:unread from:alice newer_than:7d"`)
- `limit` (optional) — Maximum number of results

**Example:**
```
Pull my recent unread emails about the Q4 report.
```

### draft_email
*(Gmail — requires connected Gmail OAuth)*

Draft an email via Gmail. The draft is staged for the data owner to review — it does NOT send until approved.

**Parameters:**
- `to` (required) — Recipient email address
- `subject` (required) — Email subject
- `body` (required) — Email body
- `purpose` (required) — Why this action is being proposed (logged for audit)
- `in_reply_to` (optional) — Message ID for threading

### send_email
*(Gmail — requires connected Gmail OAuth)*

Send an email via Gmail. The action is staged for the data owner to review — it does NOT execute until approved.

**Parameters:**
- `to` (required) — Recipient email address
- `subject` (required) — Email subject
- `body` (required) — Email body
- `purpose` (required) — Why this action is being proposed (logged for audit)
- `in_reply_to` (optional) — Message ID for threading

### reply_to_email
*(Gmail — requires connected Gmail OAuth)*

Reply to an email via Gmail. The reply is staged for the data owner to review — it does NOT send until approved.

**Parameters:**
- `to` (required) — Recipient email address
- `subject` (required) — Email subject
- `body` (required) — Email body
- `in_reply_to` (required) — Message ID of the email being replied to
- `purpose` (required) — Why this action is being proposed (logged for audit)

### search_github_issues
*(GitHub — requires connected GitHub OAuth)*

Search GitHub issues. Data is filtered according to the owner's access control policy.

**Parameters:**
- `purpose` (required) — Why this data is needed (logged for audit)
- `query` (optional) — Search query for issues
- `limit` (optional) — Maximum number of results

### search_github_prs
*(GitHub — requires connected GitHub OAuth)*

Search GitHub pull requests. Data is filtered according to the owner's access control policy.

**Parameters:**
- `purpose` (required) — Why this data is needed (logged for audit)
- `query` (optional) — Search query for pull requests
- `limit` (optional) — Maximum number of results

## Direct API Fallback

If the MCP tools above are not available, you can call the PersonalDataHub API directly via HTTP.

**Config:** Read `~/.pdh/config.json` to get `hubUrl`.

**Pull data:**
```bash
curl -X POST <hubUrl>/app/v1/pull \
  -H "Content-Type: application/json" \
  -d '{"source": "gmail", "purpose": "reason for pulling data"}'
```

**Propose an action:**
```bash
curl -X POST <hubUrl>/app/v1/propose \
  -H "Content-Type: application/json" \
  -d '{"source": "gmail", "action_type": "draft_email", "action_data": {"to": "...", "subject": "...", "body": "..."}, "purpose": "reason for action"}'
```

## Troubleshooting

If calls fail, check if the PersonalDataHub server is running:
```bash
curl <hubUrl>/health
```

If the server is not running, find and start it:
```bash
# Check where PersonalDataHub is installed
cat ~/.pdh/config.json   # look at hubDir
# Start the server
cd <hubDir> && node dist/index.js
```

## Setup

The install hook bootstraps PersonalDataHub automatically:
1. Installs dependencies, builds the project, initializes the database
2. Saves hub URL and directory to `~/.pdh/config.json`
3. Starts the server in the background

After installation, open `http://localhost:3000` to connect Gmail/GitHub via OAuth.

Agents read config automatically from `~/.pdh/config.json` — no manual configuration needed.

## Query Syntax (Gmail)

- `is:unread` — unread emails
- `from:alice` — emails from Alice
- `newer_than:7d` — emails from the last 7 days
- `subject:report` — emails with "report" in subject
- Combine: `is:unread from:alice newer_than:7d`

## Important Notes

- **Data is filtered**: The owner controls which fields you see. Some fields may be missing or redacted.
- **Actions require approval**: All outbound actions (emails, drafts) go to a staging queue. The owner must approve before execution.
- **Everything is audited**: Every pull and propose is logged with your purpose string.

---

## 中文说明

# PersonalDataHub

通过 PersonalDataHub 访问控制网关，访问来自 Gmail、GitHub 及其他来源的个人数据。数据所有者控制代理能看到什么、哪些字段可见、什么内容被编辑屏蔽，以及允许哪些操作。

## MCP 设置（推荐）

PersonalDataHub 提供一个 MCP 服务器以实现原生工具发现。将其添加到你的 Claude Code 配置中（`.claude/settings.json`）：

```json
{
  "mcpServers": {
    "personaldatahub": {
      "command": "npx",
      "args": ["pdh", "mcp"]
    }
  }
}
```

这会动态注册特定来源的工具——只有已连接 OAuth 令牌的来源才会获得工具。

## 工具

### read_emails
*(Gmail — 需要已连接的 Gmail OAuth)*

从 Gmail 提取电子邮件。数据会根据所有者的访问控制策略进行过滤和编辑屏蔽。

**参数：**
- `purpose`（必填）— 为何需要此数据（记录以供审计）
- `query`（可选）— Gmail 搜索查询（例如 `"is:unread from:alice newer_than:7d"`）
- `limit`（可选）— 最大结果数

**示例：**
```
Pull my recent unread emails about the Q4 report.
```

### draft_email
*(Gmail — 需要已连接的 Gmail OAuth)*

通过 Gmail 起草一封电子邮件。该草稿会暂存以供数据所有者审阅——在获得批准之前不会发送。

**参数：**
- `to`（必填）— 收件人电子邮件地址
- `subject`（必填）— 邮件主题
- `body`（必填）— 邮件正文
- `purpose`（必填）— 为何提出此操作（记录以供审计）
- `in_reply_to`（可选）— 用于会话串联的消息 ID

### send_email
*(Gmail — 需要已连接的 Gmail OAuth)*

通过 Gmail 发送一封电子邮件。该操作会暂存以供数据所有者审阅——在获得批准之前不会执行。

**参数：**
- `to`（必填）— 收件人电子邮件地址
- `subject`（必填）— 邮件主题
- `body`（必填）— 邮件正文
- `purpose`（必填）— 为何提出此操作（记录以供审计）
- `in_reply_to`（可选）— 用于会话串联的消息 ID

### reply_to_email
*(Gmail — 需要已连接的 Gmail OAuth)*

通过 Gmail 回复一封电子邮件。该回复会暂存以供数据所有者审阅——在获得批准之前不会发送。

**参数：**
- `to`（必填）— 收件人电子邮件地址
- `subject`（必填）— 邮件主题
- `body`（必填）— 邮件正文
- `in_reply_to`（必填）— 被回复邮件的消息 ID
- `purpose`（必填）— 为何提出此操作（记录以供审计）

### search_github_issues
*(GitHub — 需要已连接的 GitHub OAuth)*

搜索 GitHub issue。数据会根据所有者的访问控制策略进行过滤。

**参数：**
- `purpose`（必填）— 为何需要此数据（记录以供审计）
- `query`（可选）— issue 的搜索查询
- `limit`（可选）— 最大结果数

### search_github_prs
*(GitHub — 需要已连接的 GitHub OAuth)*

搜索 GitHub pull request。数据会根据所有者的访问控制策略进行过滤。

**参数：**
- `purpose`（必填）— 为何需要此数据（记录以供审计）
- `query`（可选）— pull request 的搜索查询
- `limit`（可选）— 最大结果数

## 直接 API 后备方案

如果上述 MCP 工具不可用，你可以通过 HTTP 直接调用 PersonalDataHub API。

**配置：** 读取 `~/.pdh/config.json` 以获取 `hubUrl`。

**提取数据：**
```bash
curl -X POST <hubUrl>/app/v1/pull \
  -H "Content-Type: application/json" \
  -d '{"source": "gmail", "purpose": "reason for pulling data"}'
```

**提出一项操作：**
```bash
curl -X POST <hubUrl>/app/v1/propose \
  -H "Content-Type: application/json" \
  -d '{"source": "gmail", "action_type": "draft_email", "action_data": {"to": "...", "subject": "...", "body": "..."}, "purpose": "reason for action"}'
```

## 故障排查

如果调用失败，检查 PersonalDataHub 服务器是否正在运行：
```bash
curl <hubUrl>/health
```

如果服务器未运行，找到并启动它：
```bash
# Check where PersonalDataHub is installed
cat ~/.pdh/config.json   # look at hubDir
# Start the server
cd <hubDir> && node dist/index.js
```

## 设置

安装钩子会自动引导 PersonalDataHub：
1. 安装依赖项、构建项目、初始化数据库
2. 将中心 URL 和目录保存到 `~/.pdh/config.json`
3. 在后台启动服务器

安装后，打开 `http://localhost:3000` 以通过 OAuth 连接 Gmail/GitHub。

代理会自动从 `~/.pdh/config.json` 读取配置——无需手动配置。

## 查询语法（Gmail）

- `is:unread` — 未读邮件
- `from:alice` — 来自 Alice 的邮件
- `newer_than:7d` — 最近 7 天的邮件
- `subject:report` — 主题中含有 "report" 的邮件
- 组合使用：`is:unread fr