> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtimelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol

## Overview

Chronologue integrates the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) to enable structured memory access, event scheduling, and tool invocation via standardized agent interfaces.

This implementation supports:

* Serving memory traces over a FastAPI or stdio MCP server
* Scheduling calendar events through Google Calendar API
* Converting `.json` memory traces to `.ics` format
* Running OpenAI or Claude-based ReAct loops to populate and update the calendar

## MCP Server Setup

The server exposes tools and resources via either `stdio_server` or `FastMCP` (FastAPI-based):

* **Tool: `sync_to_google_calendar`**\
  Sync `.json` memory traces to a Google Calendar
* **Tool: `generate_embedding`**\
  Generate OpenAI embeddings for trace content
* **Tool: `convert_trace_to_ics`**\
  Convert memory trace to `.ics` string for calendar export

Scripts:

* `server.py` (stdio server)
* `server_google_calendar.py` (FastAPI)

Run with:

```
python mcp/server.py  
```

or

```
python mcp/server_google_calendar.py
```

## MCP Client: Chat + Tool Invocation

The client connects to the MCP server, lists available tools, and forwards user queries through a Claude (or OpenAI) chat loop.

Key features:

* Uses Claude 3.5 Sonnet API with tools attached
* Handles tool calls like `sync_to_google_calendar`, embedding generation
* Supports a full interactive REPL

Script:

* `client.py`

Run with:

```
python mcp/client.py 
```

## Calendar Tooling and Integration

Chronologue exposes structured tools to bridge memory traces and calendar APIs:

### Key Tools

* `convert_trace_to_ics(trace: dict) -> str`\
  Converts a single memory trace into a VEVENT-compliant `.ics` string

* `sync_traces_to_google(traces: list[dict]) -> str`\
  Sends memory traces to Google Calendar using OAuth-authenticated API

* `load_memory_file(file_path: str) -> list[dict]`\
  Loads structured memory from a `.json` file

Defined in:

* `server_google_calendar.py`

Google Calendar setup requires:

* `calendar/credentials.json`
* `calendar/token.json`

Scopes used:\
`['https://www.googleapis.com/auth/calendar']`

## MCP Resources

Memory traces can be exposed as structured resources via MCP:

* `calendar://pending_goals`\
  All `goal`-type memory traces with `completion_status: pending`

* `calendar://week_summary/{iso_week}`\
  All traces from the specified ISO week (`2025-W18`)

* `calendar://trace_by_id/{trace_id}`\
  Lookup a specific memory trace by ID

These allow downstream agents or apps to reflect, plan, or retrieve specific event blocks.

## Agent Loop (Planner + Executor)

Chronologue supports integration with OpenAI or Claude models to generate schedules:

1. Query the MCP server for memory or context blocks
2. Pass them into a prompt:\
   *"Given the user's upcoming goals and availability, what events should be scheduled this week?"*
3. Receive a response in the form of `MCPContextBlock(type="calendar_event")`
4. Sync to calendar using tools

This loop is defined in the `process_query()` and `chat_loop()` methods of the `MCPClient`.

## Optional: Custom UI for Calendar + Agent Logs

For deeper integration or review:

* **Top panel**: MCP-derived upcoming events
* **Side panel**: agent chat logs and memory trace history
* **Bottom panel**: annotate traces, schedule goals, or trigger planner

Tools:

* `Streamlit` or `Flet` for simple UI prototyping
* `Tempo Tokens`, feedback inputs, and calendar visualizations

## Example Usage

Run the FastAPI-based MCP server and query events for the week:

python server\_google\_calendar.py\
curl [http://localhost:8000/context?type=calendar\_event\&last\_n=5](http://localhost:8000/context?type=calendar_event\&last_n=5)

Trigger syncing memory to calendar:

```
python mcp/client.py 
python mcp/server.py  
```

# Then: Type "Sync last session to calendar"

## Summary

Chronologue’s MCP backend provides a powerful interface for:

* Agent reflection, planning, and memory access
* Tool invocation via structured protocols
* Real-world event scheduling grounded in memory
* Integrating `.ics`, `.json`, and calendar APIs in a unified loop

Use MCP as the bridge between memory traces, LLM agents, and the real-world temporal context.

***

## System Design: Chronologue + MCP

Chronologue integrates structured memory traces, natural language input, and calendar-based coordination through a unified interface. It relies on the **Model Context Protocol (MCP)** to connect user input with event memory, agent reasoning, and calendar output.

**Event Schema**

All memory traces are converted into structured events, enabling both human review and agent planning. The core event types include:

* `goal` – a future-oriented intent ("Finish literature review")

* `observation` – a passive or descriptive record ("Met with advisor")

* `reflection` – a qualitative note or summary ("Need to prioritize data cleanup")

* `scheduled_event` – a time-bound commitment ("Lab sync at 2PM Thursday")

Example (backend JSON trace format):

```
{
  "type": "goal",
  "title": "Submit IRB application",
  "timestamp": "2025-04-24T09:00:00",
  "duration": 60,
  "linked_memory": ["trace_041", "trace_038"],
  "notes": "Dependent on finishing protocol write-up"
}
```

**MCP Integration**

MCP provides the scaffolding to structure agent interaction across time. Key mechanisms:

* **Memory Trace Ingestion**

  Conversational input is parsed into structured trace entries (goal, reflection, etc.)

* **Timeline Generation**

  MCP organizes these traces into a coherent timeline—annotated with metadata and available for `.ics` export.

* **Conversational Routing**\
  Chat commands like `"schedule a writing block tomorrow"` are interpreted into:

  * Actionable event traces

  * `.ics` entries

  * Planning context for future agent tasks

  **Calendar API Bridge**

Calendar interoperability is a core feature. MCP can generate and ingest:

* **`.ics` files** – Standards-compliant events compatible with Apple Calendar, Google Calendar, Outlook

* **Google Calendar API** – OAuth-authenticated event sync for read/write access

* **Structured Event I/O** – Sync back updated events into memory system for trace consistency

```
User Input → MCP → Trace Schema (Goal/Reflection/Event)
           → Timeline Assembly → .ics Export
           → Calendar Render → Agent Action
                            ↘ Memory Update ↖
```

**User Interface and Editable Markdown Table**

This is how the Chronologue interface is rendered in a chat-based or UI-driven interaction—clear, editable, and structured for both human interaction and `.ics` export:

```
| Time           | Task                      | Notes                          |
|----------------|---------------------------|--------------------------------|
| 07:30–08:00    | Morning routine           | Stretching, quick shower       |
| 08:00–09:00    | Breakfast + Reading       | Light news or book time        |
| 09:00–12:00    | Focus work block          | Deep work, no distractions     |
| 12:00–13:00    | Lunch                     | Away from desk                 |
| 13:00–15:00    | Meetings                  | Check calendar for links       |
| 15:00–15:30    | Break                     | Walk or coffee                 |
| 15:30–17:00    | Admin & Emails            | Inbox zero, light tasks        |
| 17:00–18:00    | Workout                   | Gym or at-home routine         |
| 18:00–19:00    | Dinner                    | Relaxed, no screens            |
| 19:00–21:00    | Personal time / Projects  | Hobbies, learning, side work   |
| 21:00–22:00    | Wind-down routine         | Read, reflect, sleep prep      |
```

This format can be edited via chat, programmatically parsed into `.ics` events, and be pushed back into the MCP memory system as scheduled traces.