Activity Log Server

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:

   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

# 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:

{
  "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:

{
  "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:

{
  "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.