chronos-mcp 0.1.1__tar.gz

chronos_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: chronos-mcp
+Version: 0.1.1
+Summary: Local-first email and calendar inbox for AI agents
+Author: Chronos Contributors
+License: MIT
+Keywords: email,calendar,gmail,mcp,agent,inbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: google-api-python-client>=2.127
+Requires-Dist: google-auth-oauthlib>=1.2
+Requires-Dist: google-auth-httplib2>=0.2
+Requires-Dist: python-ulid>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# Chronos — agent-inbox
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+Local-first email and calendar inbox for AI agents. Syncs Gmail and Google Calendar
+into a single queryable SQLite database and exposes all data through an MCP server.
+
+## Features
+
+- Sync multiple Gmail and Google Calendar accounts into one SQLite database
+- Full-text search via FTS5 (messages and events)
+- MCP server at `localhost:7071/sse` for agent integration
+- HTTP REST API at `localhost:7070` for direct queries
+- Read-only SQL interface via `POST /v1/query`
+- Optimistic event writes with provider-wins conflict resolution
+- Incremental sync with historyId (Gmail) and syncToken (Calendar)
+- ULID primary keys, WAL mode, no cloud dependencies at query time
+
+## Installation
+
+```bash
+pipx install chronos-mcp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/CourtimusPrime/chronos.git
+cd chronos
+pip install -e .
+```
+
+## Setup
+
+### Prerequisites
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a project and enable **Gmail API** and **Google Calendar API**
+3. Create an OAuth client ID (Desktop app type)
+4. Download the credentials JSON file
+
+### Register an account
+
+> Run `chronos --help` for full Google Cloud Console setup instructions.
+
+```bash
+# Step 1: Stage your credentials (Desktop app OAuth JSON from Google Cloud Console)
+chronos --use /path/to/credentials.json
+
+# Step 2: Register an account (opens browser for OAuth2 consent)
+chronos --add personal
+```
+
+Staged credentials persist until the next `--use` call, so you can register
+multiple accounts with one credentials file:
+
+```bash
+chronos --use /path/to/credentials.json
+chronos --add personal
+chronos --add work
+```
+
+The `--add` step:
+
+- Writes `~/.chronos/personal_token.json` (self-contained token file)
+- Creates two rows in the accounts table (gmail + google_calendar)
+- Prints a confirmation summary
+
+### Start syncing
+
+```bash
+chronos --start
+```
+
+The daemon starts on `127.0.0.1:7070` (HTTP) and `127.0.0.1:7071` (MCP/SSE).
+
+## CLI Reference
+
+```
+chronos --use CREDENTIALS_PATH          # Stage a credentials JSON for --add
+chronos --add ALIAS                     # Register a new account (requires prior --use)
+chronos --remove ALIAS                  # Remove an account and its data
+chronos --list                          # List all registered accounts
+chronos --test ALIAS                    # Test account tokens
+chronos --start [--http-port N] [--mcp-port N]  # Start daemon
+chronos --stop                          # Stop the running daemon (preserves synced data)
+chronos --status                        # Show sync status
+chronos --sync [ALIAS] [--type full|incremental]  # Trigger sync
+```
+
+> **Ctrl+C vs --stop:** Pressing Ctrl+C while `chronos --start` is running wipes
+> synced data (emails, threads, events, calendars) but preserves accounts.
+> Use `chronos --stop` from another terminal for a clean shutdown that preserves data.
+>
+> Run `chronos --help` for Google Cloud Console setup steps.
+
+## Environment Variables
+
+| Variable            | Default                    | Description                        |
+| ------------------- | -------------------------- | ---------------------------------- |
+| `CHRONOS_HOME`      | `~/.chronos`               | Credentials and database directory |
+| `CHRONOS_DB_PATH`   | `$CHRONOS_HOME/chronos.db` | SQLite database file               |
+| `CHRONOS_HTTP_PORT` | `7070`                     | HTTP API port                      |
+| `CHRONOS_MCP_PORT`  | `7071`                     | MCP server port                    |
+| `CHRONOS_LOG_LEVEL` | `INFO`                     | Log level                          |
+
+## License
+
+MIT

chronos_mcp-0.1.1/README.md

@@ -0,0 +1,110 @@
+# Chronos — agent-inbox
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+Local-first email and calendar inbox for AI agents. Syncs Gmail and Google Calendar
+into a single queryable SQLite database and exposes all data through an MCP server.
+
+## Features
+
+- Sync multiple Gmail and Google Calendar accounts into one SQLite database
+- Full-text search via FTS5 (messages and events)
+- MCP server at `localhost:7071/sse` for agent integration
+- HTTP REST API at `localhost:7070` for direct queries
+- Read-only SQL interface via `POST /v1/query`
+- Optimistic event writes with provider-wins conflict resolution
+- Incremental sync with historyId (Gmail) and syncToken (Calendar)
+- ULID primary keys, WAL mode, no cloud dependencies at query time
+
+## Installation
+
+```bash
+pipx install chronos-mcp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/CourtimusPrime/chronos.git
+cd chronos
+pip install -e .
+```
+
+## Setup
+
+### Prerequisites
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a project and enable **Gmail API** and **Google Calendar API**
+3. Create an OAuth client ID (Desktop app type)
+4. Download the credentials JSON file
+
+### Register an account
+
+> Run `chronos --help` for full Google Cloud Console setup instructions.
+
+```bash
+# Step 1: Stage your credentials (Desktop app OAuth JSON from Google Cloud Console)
+chronos --use /path/to/credentials.json
+
+# Step 2: Register an account (opens browser for OAuth2 consent)
+chronos --add personal
+```
+
+Staged credentials persist until the next `--use` call, so you can register
+multiple accounts with one credentials file:
+
+```bash
+chronos --use /path/to/credentials.json
+chronos --add personal
+chronos --add work
+```
+
+The `--add` step:
+
+- Writes `~/.chronos/personal_token.json` (self-contained token file)
+- Creates two rows in the accounts table (gmail + google_calendar)
+- Prints a confirmation summary
+
+### Start syncing
+
+```bash
+chronos --start
+```
+
+The daemon starts on `127.0.0.1:7070` (HTTP) and `127.0.0.1:7071` (MCP/SSE).
+
+## CLI Reference
+
+```
+chronos --use CREDENTIALS_PATH          # Stage a credentials JSON for --add
+chronos --add ALIAS                     # Register a new account (requires prior --use)
+chronos --remove ALIAS                  # Remove an account and its data
+chronos --list                          # List all registered accounts
+chronos --test ALIAS                    # Test account tokens
+chronos --start [--http-port N] [--mcp-port N]  # Start daemon
+chronos --stop                          # Stop the running daemon (preserves synced data)
+chronos --status                        # Show sync status
+chronos --sync [ALIAS] [--type full|incremental]  # Trigger sync
+```
+
+> **Ctrl+C vs --stop:** Pressing Ctrl+C while `chronos --start` is running wipes
+> synced data (emails, threads, events, calendars) but preserves accounts.
+> Use `chronos --stop` from another terminal for a clean shutdown that preserves data.
+>
+> Run `chronos --help` for Google Cloud Console setup steps.
+
+## Environment Variables
+
+| Variable            | Default                    | Description                        |
+| ------------------- | -------------------------- | ---------------------------------- |
+| `CHRONOS_HOME`      | `~/.chronos`               | Credentials and database directory |
+| `CHRONOS_DB_PATH`   | `$CHRONOS_HOME/chronos.db` | SQLite database file               |
+| `CHRONOS_HTTP_PORT` | `7070`                     | HTTP API port                      |
+| `CHRONOS_MCP_PORT`  | `7071`                     | MCP server port                    |
+| `CHRONOS_LOG_LEVEL` | `INFO`                     | Log level                          |
+
+## License
+
+MIT

chronos_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chronos-mcp"
+version = "0.1.1"
+description = "Local-first email and calendar inbox for AI agents"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Chronos Contributors" }]
+keywords = ["email", "calendar", "gmail", "mcp", "agent", "inbox"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "fastapi>=0.111",
+    "uvicorn[standard]>=0.29",
+    "mcp[cli]>=1.0",
+    "google-api-python-client>=2.127",
+    "google-auth-oauthlib>=1.2",
+    "google-auth-httplib2>=0.2",
+    "python-ulid>=2.0",
+    "httpx>=0.27",
+    "click>=8.1",
+    "rich>=13.0",
+    "aiofiles>=23.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+chronos = "chronos.__main__:main"
+
+[tool.pytest.ini_options]
+addopts = "--cov=chronos --cov-report=term-missing --cov-report=html --cov-report=xml"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["src/chronos"]
+omit = [
+    "*/__main__.py",
+    "tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+skip_covered = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"

chronos_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chronos_mcp-0.1.1/src/chronos/__init__.py

@@ -0,0 +1,4 @@
+"""Chronos — agent-inbox: local-first email and calendar sync daemon."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

chronos_mcp-0.1.1/src/chronos/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point: chronos CLI."""
+import sys
+
+
+def main():
+    """Main entry point for the chronos CLI."""
+    from chronos.cli.main import cli
+    cli()
+
+
+if __name__ == "__main__":
+    main()

chronos_mcp-0.1.1/src/chronos/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API package."""

chronos_mcp-0.1.1/src/chronos/api/app.py

@@ -0,0 +1,49 @@
+"""FastAPI app factory with envelope middleware."""
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from chronos.api.routes import accounts, calendars, events, messages, query, sync
+
+
+def create_app(db_path: Optional[str] = None, sync_engine=None) -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Chronos HTTP API",
+        description="Local-first email and calendar inbox for AI agents",
+        version="0.1.0",
+    )
+
+    # Store state
+    app.state.db_path = db_path
+    app.state.sync_engine = sync_engine
+
+    # CORS (localhost only, no credentials)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Register routers with v1 prefix
+    app.include_router(accounts.router, prefix="/v1")
+    app.include_router(messages.router, prefix="/v1")
+    app.include_router(calendars.router, prefix="/v1")
+    app.include_router(events.router, prefix="/v1")
+    app.include_router(sync.router, prefix="/v1")
+    app.include_router(query.router, prefix="/v1")
+
+    @app.get("/")
+    def root():
+        return {"service": "chronos", "version": "0.1.0"}
+
+    @app.get("/health")
+    def health():
+        return {"ok": True, "data": {"status": "healthy"}, "error": None}
+
+    return app

chronos_mcp-0.1.1/src/chronos/api/deps.py

@@ -0,0 +1,23 @@
+"""DB dependency injection for FastAPI."""
+from __future__ import annotations
+
+import sqlite3
+from typing import Generator
+
+from fastapi import Request
+
+
+def get_db(request: Request) -> Generator[sqlite3.Connection, None, None]:
+    """FastAPI dependency that provides a DB connection per request."""
+    db_path = request.app.state.db_path
+    from chronos.db.connection import get_connection
+    conn = get_connection(db_path)
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+
+def get_sync_engine(request: Request):
+    """FastAPI dependency that provides the SyncEngine."""
+    return getattr(request.app.state, "sync_engine", None)

chronos_mcp-0.1.1/src/chronos/api/errors.py

@@ -0,0 +1,49 @@
+"""All error codes from PRD §12."""
+from __future__ import annotations
+
+from fastapi import HTTPException
+from fastapi.responses import JSONResponse
+
+
+def error_response(code: str, message: str, status_code: int) -> JSONResponse:
+    """Return a standard error envelope response."""
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "ok": False,
+            "data": None,
+            "error": {"code": code, "message": message},
+        },
+    )
+
+
+def ok_response(data) -> dict:
+    """Return a standard success envelope."""
+    return {"ok": True, "data": data, "error": None}
+
+
+def list_response(items: list, total: int, limit: int, offset: int) -> dict:
+    """Return a paginated list envelope."""
+    return ok_response({
+        "items": items,
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+        "has_more": (offset + len(items)) < total,
+    })
+
+
+# Error code constants
+ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND"
+MESSAGE_NOT_FOUND = "MESSAGE_NOT_FOUND"
+EVENT_NOT_FOUND = "EVENT_NOT_FOUND"
+THREAD_NOT_FOUND = "THREAD_NOT_FOUND"
+CALENDAR_NOT_FOUND = "CALENDAR_NOT_FOUND"
+WRITE_NOT_ALLOWED = "WRITE_NOT_ALLOWED"
+INVALID_SQL = "INVALID_SQL"
+QUERY_RESULT_EMPTY = "QUERY_RESULT_EMPTY"
+EVENT_READ_ONLY = "EVENT_READ_ONLY"
+PENDING_CHANGE_EXISTS = "PENDING_CHANGE_EXISTS"
+SYNC_NOT_RUNNING = "SYNC_NOT_RUNNING"
+PROVIDER_ERROR = "PROVIDER_ERROR"
+INVALID_BODY = "INVALID_BODY"

chronos_mcp-0.1.1/src/chronos/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes package."""

chronos_mcp-0.1.1/src/chronos/api/routes/accounts.py

@@ -0,0 +1,36 @@
+"""GET /v1/accounts endpoint."""
+from __future__ import annotations
+
+import sqlite3
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+
+from chronos.api.deps import get_db
+from chronos.api.errors import list_response, ok_response
+
+router = APIRouter()
+
+
+def _account_to_dict(row: sqlite3.Row) -> dict:
+    """Serialize account row (never include auth_data)."""
+    return {
+        "id": row["id"],
+        "provider": row["provider"],
+        "email": row["email"],
+        "display_name": row["display_name"],
+        "sync_enabled": bool(row["sync_enabled"]),
+        "last_synced_at": row["last_synced_at"],
+        "created_at": row["created_at"],
+    }
+
+
+@router.get("/accounts")
+def list_accounts(conn: Annotated[sqlite3.Connection, Depends(get_db)]):
+    """GET /v1/accounts — Returns all accounts."""
+    rows = conn.execute(
+        "SELECT * FROM accounts ORDER BY created_at"
+    ).fetchall()
+
+    items = [_account_to_dict(r) for r in rows]
+    return list_response(items, len(items), 50, 0)

chronos_mcp-0.1.1/src/chronos/api/routes/calendars.py

@@ -0,0 +1,59 @@
+"""Calendars endpoint."""
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Annotated, Optional
+
+from fastapi import APIRouter, Depends, Query
+
+from chronos.api.deps import get_db
+from chronos.api.errors import list_response
+
+router = APIRouter()
+
+
+def _calendar_to_dict(row: sqlite3.Row) -> dict:
+    return {
+        "id": row["id"],
+        "account_id": row["account_id"],
+        "provider_calendar_id": row["provider_calendar_id"],
+        "name": row["name"],
+        "description": row["description"],
+        "color": row["color"],
+        "is_primary": bool(row["is_primary"]),
+        "is_read_only": bool(row["is_read_only"]),
+        "timezone": row["timezone"],
+        "created_at": row["created_at"],
+    }
+
+
+@router.get("/calendars")
+def list_calendars(
+    conn: Annotated[sqlite3.Connection, Depends(get_db)],
+    account_id: Optional[str] = None,
+    limit: int = Query(default=50, ge=1, le=500),
+    offset: int = Query(default=0, ge=0),
+):
+    """GET /v1/calendars — List calendars."""
+    conditions = []
+    params = []
+
+    if account_id:
+        conditions.append("account_id = ?")
+        params.append(account_id)
+
+    where_clause = "WHERE " + " AND ".join(conditions) if conditions else ""
+
+    count_row = conn.execute(
+        f"SELECT COUNT(*) FROM calendars {where_clause}", params
+    ).fetchone()
+    total = count_row[0]
+
+    rows = conn.execute(
+        f"SELECT * FROM calendars {where_clause} ORDER BY is_primary DESC, name LIMIT ? OFFSET ?",
+        params + [limit, offset],
+    ).fetchall()
+
+    items = [_calendar_to_dict(r) for r in rows]
+    return list_response(items, total, limit, offset)