# Activity Log MCP Server & Dashboard

A complete, persistent activity log system built with TypeScript. It allows any Model Context Protocol (MCP) compatible AI assistant (Gemini, Claude, Cursor, etc.) to log events, decisions, and system logs over HTTP, and provides a sleek vanilla web dashboard to inspect, search, filter, and monitor the ledger in real-time.

Designed with a **"black box flight recorder / terminal ledger"** aesthetic, and backed by a local JSON file database.

---

## Technical Stack
- **MCP Server**: FastMCP (TypeScript) using `httpStream` transport for remote access.
- **Dashboard Backend**: Express.js serving static assets and REST API endpoints.
- **Dashboard Frontend**: Plain HTML, custom modern CSS, and vanilla JS with a responsive dark terminal aesthetic (paired fonts, dynamic tag colors per client source, automatic debounced search, collapsible metadata blocks, and ID hashing to optimize redraws).
- **Database**: Local filesystem JSON storage (`activity_log.json` in the project root).

---

## Getting Started

### 1. Environment Variables Configuration
1. Copy the example environment file:
   ```bash
   cp .env.example .env
   ```
2. Fill in the values inside `.env` (optional):
   - `MCP_PORT`: The port for the MCP server (default: `8787`).
   - `DASHBOARD_PORT`: The port for the web dashboard (default: `4000`).

### 2. Installation & Build
```bash
# Install dependencies
npm install

# Compile TypeScript
npm run build

# Start both servers (MCP Server + Dashboard Backend) concurrently
npm start
```
Upon start, the local JSON file database `activity_log.json` will be automatically initialized in the project root as log entries arrive.

---

## Connecting an AI Client

Since the server is initialized with `transportType: "httpStream"`, it runs as a remote server over HTTP rather than stdio. Any MCP-compatible AI assistant can connect to it.

The server exposes two main endpoints:
* **HTTP Streaming (Streamable HTTP)**: `http://localhost:8787/mcp` (Used by modern clients like Gemini / Google Antigravity).
* **SSE (Server-Sent Events)**: `http://localhost:8787/sse` (Used by standard SSE clients like Cursor or the MCP Inspector).

---

### A. Cursor IDE Configuration

You can configure Cursor to use this server either globally or on a project level.

#### Option 1: Project-Specific Configuration
Create a `.cursor/mcp.json` file in the root of your Cursor workspace and add:
```json
{
  "mcpServers": {
    "activity-log": {
      "type": "sse",
      "url": "http://localhost:8787/sse"
    }
  }
}
```

#### Option 2: Global Configuration via Settings GUI
1. Open Cursor Settings (click the Gear icon in the top-right corner).
2. Go to **Features** -> **MCP**.
3. Click **+ Add New MCP Server**.
4. Set:
   - **Name**: `activity-log`
   - **Type**: `SSE`
   - **URL**: `http://localhost:8787/sse`
5. Click **Save**.

---

### B. Google Antigravity IDE Configuration

To register the server globally inside the Antigravity IDE:
1. Open the settings file `~/.gemini/config/mcp_config.json` in your user profile directory.
2. Add your server under `mcpServers` using the `serverUrl` parameter:
```json
{
  "mcpServers": {
    "activity-log": {
      "serverUrl": "http://localhost:8787/mcp"
    }
  }
}
```
3. Save the file and click **Refresh** in the IDE settings panel.

---

### C. Claude Desktop Configuration
To configure Claude Desktop to connect to this server, edit your `claude_desktop_config.json` (located at `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add:

```json
{
  "mcpServers": {
    "activity-log": {
      "command": "node",
      "args": [
        "c:/Projects/save-mcp/dist/server.js"
      ],
      "env": {
        "MCP_PORT": "8787"
      }
    }
  }
}
```

---

## Exposed MCP Tools

The MCP server exposes three main tools:
1. **`log_activity`**: Saves an activity entry.
   - `source` (string): The client source name (e.g., `"claude"`, `"gemini"`, `"cursor"`).
   - `action_type` (string): The action category (e.g., `"chat"`, `"code_edit"`, `"decision"`, `"error"`).
   - `content` (string): The main body text/log contents.
   - `metadata` (object, optional): A key-value object of structured context.
2. **`get_activity`**: Retrieves activity logs.
   - `source` (string, optional): Filter by client source.
   - `action_type` (string, optional): Filter by action type.
   - `limit` (number, default `20`, max `200`): Maximum entries to fetch.
3. **`delete_activity`**: Deletes a specific entry.
   - `id` (uuid string): The unique identifier of the entry to delete.

---

## Deployed Mode (Cloud Deployment)

To allow multiple devices or external clients (like cloud-hosted Gemini/Claude API scripts) to log actions to the same database:
1. Deploy this codebase to a cloud platform like **Railway**, **Fly.io**, or **Render**.
2. Expose the environment variables (`MCP_PORT`, `DASHBOARD_PORT`) in your cloud provider's dashboard.
3. **Persistent Disk**: If deploying to container environments, make sure to mount a persistent disk volume to ensure your `activity_log.json` survives restarts.