# RAG_0 MCP Task Planner

RAG_0 is a local Python MCP server built with FastMCP. It turns one project task into connected work items across GitHub, Notion, and Google Calendar.

The main tool, `create_project_task`, validates a task, creates a GitHub issue, creates a Notion task page with the GitHub link, creates a Google Calendar event with both links, then updates the Notion page with the Calendar event URL.

## Connected Tools

- GitHub Issues: tracks the engineering task.
- Notion Database: stores the task, status, priority, due date, and links.
- Google Calendar: schedules focused work time for the task.

## Setup

Create and activate a virtual environment:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

Install dependencies:

```powershell
python -m pip install -r requirements.txt
```

Create your local environment file:

```powershell
Copy-Item .env.example .env
```

Edit `.env` with your real credentials. Keep `DRY_RUN=true` until you are ready to call real APIs.

## Required Environment Variables

- `DRY_RUN`: `true` or `false`
- `MCP_TRANSPORT`: `stdio` or `http`; defaults to `stdio`
- `HOST`: HTTP host, defaults to `0.0.0.0`
- `PORT`: HTTP port, defaults to `8000`
- `LOG_LEVEL`: optional Python logging level; defaults to `INFO`
- `GITHUB_TOKEN`
- `GITHUB_OWNER`
- `GITHUB_REPO`
- `NOTION_TOKEN`
- `NOTION_DATABASE_ID`
- `NOTION_DATA_SOURCE_ID`: optional; use when targeting a specific Notion data source
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `GOOGLE_REFRESH_TOKEN`
- `GOOGLE_CALENDAR_ID`

## Run Locally

The default transport is `stdio`, which is best for local MCP clients and MCP Inspector:

```powershell
python server.py
```

To run the HTTP transport locally:

```powershell
$env:MCP_TRANSPORT="http"
$env:DRY_RUN="true"
python server.py
```

The HTTP transport uses the MCP SDK streamable HTTP transport and listens on `HOST` and `PORT`. By default, that is `0.0.0.0:8000`.

The server exposes these MCP tools:

- `create_project_task`
- `health_check`

## Test DRY_RUN

Run all tests:

```powershell
python -m pytest tests -q
```

Run only the local dry-run workflow test:

```powershell
python -m pytest tests\test_dry_run_workflow.py -q
```

Run the assignment evals:

```powershell
python -m pytest evals -q
```

When `DRY_RUN=true`, no real GitHub, Notion, or Google Calendar API calls are made. The services return fake IDs and URLs.

## Deploy on Render or Railway

This server can run in deployment using HTTP transport. Keep `DRY_RUN=true` for first deployment checks, then switch to `DRY_RUN=false` only after all production credentials are configured.

### Render

1. Create a new Web Service from your repository.
2. Use Python as the runtime.
3. Set the build command:

```bash
pip install -r requirements.txt
```

4. Set the start command:

```bash
python server.py
```

5. Add environment variables in the Render dashboard:

```text
MCP_TRANSPORT=http
DRY_RUN=true
HOST=0.0.0.0
PORT=8000
GITHUB_TOKEN=your-production-github-token
GITHUB_OWNER=your-github-owner
GITHUB_REPO=your-repo-name
NOTION_TOKEN=your-production-notion-token
NOTION_DATABASE_ID=your-notion-database-id
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REFRESH_TOKEN=your-google-refresh-token
GOOGLE_CALENDAR_ID=primary
```

Do not put real secrets in `README.md`, `.env.example`, or source code. Add production values only in the Render environment variable dashboard.

### Railway

1. Create a new Railway project from your repository.
2. Set the start command:

```bash
python server.py
```

3. Add the same environment variables in the Railway Variables dashboard:

```text
MCP_TRANSPORT=http
DRY_RUN=true
HOST=0.0.0.0
PORT=8000
```

Then add the GitHub, Notion, and Google Calendar production variables in the dashboard. Railway may provide its own `PORT`; if it does, use Railway's provided value.

For deployed HTTP transport, MCP clients should connect to the hosted service's `/mcp` endpoint unless your hosting or MCP client requires a different URL format.

## Connect to MCP Client

Use this server as a local stdio MCP server. Run your MCP client from the project root so `server.py` and `.env` resolve correctly.

Example MCP client configuration:

```json
{
  "mcpServers": {
    "task-planner": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "DRY_RUN": "true"
      }
    }
  }
}
```

In real usage, secrets should be loaded from `.env`, not written directly into the MCP client config. The `env` block above is only useful for simple local overrides like `DRY_RUN=true`.

On Windows, activate the virtual environment before running the MCP client or Inspector from the project root:

```powershell
.\.venv\Scripts\Activate.ps1
```

You can test the server with MCP Inspector:

```powershell
npx @modelcontextprotocol/inspector python server.py
```

Then open the Inspector URL shown in the terminal, select the `Tools` tab, choose `create_project_task`, and run it with a dry-run payload such as:

```json
{
  "title": "Finish MCP Report",
  "description": "Write documentation and prepare demo",
  "due_date": "2026-07-10",
  "duration_minutes": 60,
  "priority": "High",
  "assignee": null
}
```

## Example Tool Input

```json
{
  "title": "Finish MCP Report",
  "description": "Write documentation and prepare demo",
  "due_date": "2026-07-10",
  "duration_minutes": 60,
  "priority": "High",
  "assignee": null
}
```

## Security Notes

- Never commit `.env`.
- Never commit OAuth files such as `token.json` or `credentials.json`.
- Use `.env.example` for placeholders only.
- Start with `DRY_RUN=true` to verify the workflow safely.
- Set `DRY_RUN=false` only after GitHub, Notion, and Google Calendar credentials are configured.