# Notion Household Finance

Codex plugin and local MCP server for managing a Notion-backed household finance workspace.

This repository is designed for a personal Notion setup with Korean household-finance databases. It provides deterministic Notion API tools for querying and writing finance records, while keeping secrets and data source IDs outside the repository.

## What This Includes

- A Codex plugin manifest at `.codex-plugin/plugin.json`
- A local MCP server at `scripts/mcp_server.mjs`
- A small CLI at `scripts/notion_household_finance.mjs`
- A Codex skill at `skills/notion-household-finance/SKILL.md`
- Example config files under `examples/`

## Requirements

- Node.js 20 or newer
- A Notion integration token with access to the target databases
- A local data source config file
- Codex plugin support

## Configuration

Create a local config file. The default location is:

```text
~/.config/household-finance/config.json
```

Use `examples/config.example.json` as the shape:

```json
{
  "databases": {
    "monthly_budget": "notion-data-source-id",
    "fixed_expense": "notion-data-source-id",
    "income_expense": "notion-data-source-id",
    "debt": "notion-data-source-id",
    "repayment": "notion-data-source-id",
    "savings_goal": "notion-data-source-id",
    "savings_record": "notion-data-source-id",
    "investment": "notion-data-source-id",
    "spending_limit": "notion-data-source-id"
  }
}
```

Set these environment variables on the machine that will run Codex:

```bash
export NOTION_TOKEN="secret_notion_token_here"
export NOTION_VERSION="2026-03-11"
```

Optional:

```bash
export HOUSEHOLD_FINANCE_CONFIG="/absolute/path/to/config.json"
```

Do not commit `.env`, local config files, Notion tokens, or real data source IDs.

## Install As A Personal Codex Plugin

Clone this repo into the personal plugin directory:

```bash
mkdir -p ~/.agents/plugins/plugins
git clone https://github.com/atototo/notion-household-finance.git ~/.agents/plugins/plugins/notion-household-finance
```

Create or update `~/.agents/plugins/marketplace.json` using `examples/marketplace.example.json` as the shape. The important plugin source path is:

```json
{
  "source": {
    "source": "local",
    "path": "./plugins/notion-household-finance"
  }
}
```

After Codex reloads plugins, the plugin should appear as `notion-household-finance@personal`.

## CLI Usage

Inspect a configured data source:

```bash
node scripts/notion_household_finance.mjs inspect-data-source income_expense
```

Query a configured data source:

```bash
node scripts/notion_household_finance.mjs query-data-source income_expense --page-size 10
```

Create a raw page:

```bash
node scripts/notion_household_finance.mjs create-page income_expense --properties-json '{"내역":{"title":[{"type":"text","text":{"content":"테스트"}}]}}'
```

## MCP Tools

The plugin exposes these MCP tools when loaded by Codex:

- `notion_hf_health_check`
- `notion_hf_inspect_data_source`
- `notion_hf_query_data_source`
- `notion_hf_create_page`
- `notion_hf_find_monthly_budget`
- `notion_hf_create_monthly_budget`
- `notion_hf_create_variable_spending_limits`
- `notion_hf_record_transaction`
- `notion_hf_record_repayment`
- `notion_hf_record_savings`

## Security

This repository should not contain:

- Notion tokens
- Real `.env` files
- Real personal finance exports
- Private Notion page IDs unless you intentionally keep the repo private

Before publishing, run a local secret scan or inspect the diff manually.