MCP Http Agent Md

🚀 mcp-http-agent-md

A minimal MCP (Model Context Protocol) HTTP server for AGENTS.md and structured tasks, featuring versioned history, an ephemeral scratchpad, and support for subagents. It also provides user isolation and project sharing capabilities.

🚀 Quick Start

This project is a minimal MCP (Model Context Protocol) HTTP server designed for AGENTS.md and structured tasks. It offers versioned history (logs/revert) and an ephemeral scratchpad, accessible via a Streamable HTTP endpoint. The scratchpad can spawn context - isolated subagents for focused task - solving. An auth middleware is provided for user isolation and public serving, and users can share and collaborate on projects.

✨ Features

• Hierarchical Context Management: Implements a hierarchical system for AI agents working on long - term projects, with project - wide and task - wide context management.
• Subagent Isolation: Each subagent has access to relevant context only, preventing information overload.
• Persistent Knowledge: Project state persists across multiple chat sessions.
• REST API for Project Sharing: Allows users to share projects with others via REST API.
• Web UI: An optional lightweight management console is available at /ui.

📦 Installation

Automatic Install and User creation (Unix - like systems)

• Without docker: Install to $HOME/.config/mcp - http - agent - md and start with a default user.

  curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install.sh | bash
  

• With docker: Data persists in $HOME/.config/mcp - http - agent - md/data.

  curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install-docker.sh | bash
  

Manual Install

1. Clone the repo:

   git clone https://github.com/benhaotang/mcp-http-agent-md.git
   

2. Environments: You can set all environments defined in .env.example in the terminal via export XXX = xxx. Or, if you prefer setting them via .env, run cp .env.example .env.
   • Server defaults: HOST = localhost, PORT = 3000, BASE_PATH = /mcp.
   • External AI (optional): Set in .env or ENV when using the subagent tools.

   USE_EXTERNAL_AI=true
   AI_API_TYPE=google   # google | openai | groq | compat | mcp
   AI_API_KEY=...   # required when enabled
   AI_MODEL="gemini-2.5-pro"  # optional; default depends on provider
   AI_TIMEOUT=120              # optional
   

   ⚠️ Important Note For docker, we currently only support adding them via -e XXX = xxx for security. If you want to use the .env file, remove it from .dockerignore and build the image locally.

3. Run with Node:
   • pnpm (recommended):
     • Install: pnpm install
     • Dev: pnpm dev
     • Prod: pnpm start
   • npm:
     • Install: npm install
     • Dev: npx nodemon --watch index.js --ext js,mjs,cjs index.js
     • Prod: npm run start
4. Docker:
   • From GitHub Package:

     docker pull ghcr.io/benhaotang/mcp-http-agent-md:latest
     

     Run (persist DB and set admin key):

     docker run -it --restart always \
       -p 3000:3000 \
       -e MAIN_API_KEY=change-me \
       -e HOST=0.0.0.0 \
       -v $(pwd)/data:/app/data \
       --name mcp-http-agent-md \
       ghcr.io/benhaotang/mcp-http-agent-md:latest
     

     Add -e AI_API_KEY = xxx -e USE_EXTERNAL_AI = true for using subagents.
   • Local Build:

     docker build -t mcp-http-agent-md .
     

💻 Usage Examples

Endpoints

• Admin API: http://localhost:3000/auth (Bearer MAIN_API_KEY). First, generate a USER_API_KEY, see Auth.
• MCP endpoint: POST http://localhost:3000/mcp?apiKey = USER_API_KEY
  • Local:

    {
      "mcpServers": {
        "mcp-agent-md": {
          "command": "npx",
          "args": ["-y","mcp-remote","http://localhost:3000/mcp?apiKey=USER_API_KEY"]
        }
      }
    }
    

  • Remote:

    {
      "mcpServers": {
        "mcp-agent-md": {
          "url": "https://<your-deployment>/mcp?apiKey=USER_API_KEY"
        }
      }
    }
    

Auth and Admin

• MCP: Supply user apiKey via query ?apiKey = ... or Authorization: Bearer ....
• Admin: Use Authorization: Bearer MAIN_API_KEY.

Create a user (returns { id, apiKey }):

curl -X POST http://localhost:3000/auth/users \
  -H "Authorization: Bearer $MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"alice"}'

Project Sharing

Share a project read - only with another user:

curl -X POST http://localhost:3000/project/share \
  -H "Authorization: Bearer $USER_API_KEY/$MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_id>","target_user_id":"<user_id>","permission":"ro"}'

MCP Endpoint

List tools:

curl -X POST 'http://localhost:3000/mcp?apiKey=USER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

Web UI (/ui)

• Dev mode: Included automatically when you run pnpm dev (hot reloading). Visit /ui once the server starts.
• Production:

  pnpm build:ui
  NODE_ENV=production pnpm start
  

📚 Documentation

Architecture Overview

This project implements a hierarchical context management system for AI agents working on long - term projects. The following Mermaid diagram illustrates the architecture:

graph LR
    subgraph "Full Project Knowledge"
        PK["📚 Entire Project<br/>• All code files<br/>• All documentation<br/>• Web resources<br/>• Tool outputs<br/>MASSIVE CONTEXT"]
    end
    
    subgraph "Compressed Knowledge"
        A["📄 AGENTS.md<br/>(Essential Knowledge)"]
        P["📋 progress.md<br/>(Task Board)"]
    end
    
    subgraph "Main Agent"
        MA["🧠 Orchestrator<br/>LOW CONTEXT<br/>• Reads compressed knowledge<br/>• Spawns scratchpads<br/>• Updates project state"]
    end
    
    subgraph "Scratchpad"
        CM["Common Memory<br/>(Shared Context)"]
        
        subgraph "Task Pool"
            T1["Task 1"]
            T2["Task 2"]
            T3["Task ..."]
        end
        
        subgraph "Subagents"
            SA1["🤖 Agent 1<br/>HIGH CONTEXT"]
            SA2["🤖 Agent 2<br/>HIGH CONTEXT"]
        end
    end
    
    %% Knowledge compression flow
    PK --> |compresses to| A
    PK --> |compresses to| P
    
    %% Main agent reads compressed knowledge
    A --> MA
    P --> MA
    
    %% Main agent creates scratchpad with smaller tasks
    MA --> |break into tasks| T1
    MA --> |break into tasks| T2
    MA --> |break into tasks| T3
    MA --> |maintains| CM
    
    %% Main agent can read/write directly
    MA <--> |read/write| CM
    MA <--> |read/write| T1
    MA <--> |read/write| T2
    MA <--> |read/write| T3
    
    %% Tasks spawn subagents
    T1 --> |spawns| SA1
    T2 --> |spawns| SA2
    
    %% Subagents get context and work on specific tasks
    SA1 --> |full access| PK
    SA2 --> |full access| PK
    CM --> |shared context| SA1
    CM --> |shared context| SA2
    
    %% Subagents report back to their tasks
    SA1 --> |results/comments| T1
    SA2 --> |results/comments| T2
    
    %% Main agent updates compressed knowledge
    MA --> |updates| A
    MA --> |updates| P

    style PK fill:#ffecb3
    style A fill:#e1f5fe
    style P fill:#e8f5e8
    style MA fill:#ffebee
    style CM fill:#f3e5f5
    style SA1 fill:#fff3e0
    style SA2 fill:#fff3e0

Key Benefits:

• Project - wide context: AGENTS.md stores accumulated knowledge, progress.md tracks long - term tasks. Read more from agents.md.
• Task - wide context: Scratchpads provide temporary but focused, manageable chunks with shared memory.
• Subagent isolation: Each subagent only sees relevant context, preventing information overload.
• Low main agent context: Orchestrator only needs high - level results, not detailed research.
• Persistent knowledge: Project state survives across multiple chat sessions.

Web UI Tools

• list_projects: List all project names.
• init_project: Create/init project { name, agent?, progress? }. Immediately creates an initial backup (commit) and returns hash.
• delete_project: Delete project { name } (owner only).
• rename_project: Rename project { oldName, newName, comment? } (owner only). Returns updated hash.
• read_agent: Read AGENTS.md { name }.
• write_agent: Write AGENTS.md { name, content, comment? }. Patch/diff also supported; responses include updated hash.
• read_progress: Read structured tasks for a project { name, only? }. Returns JSON { tasks: [...], markdown: "..." } where markdown is a nested, human - friendly outline. only filters by pending | in_progress | completed | archived (synonyms accepted). By default, archived tasks are excluded; they are included only if only contains archived.
• progress_add: Add one or more structured tasks { name, item, comment? }. Creates a commit when tasks are added; returns hash.
• progress_set_new_state: Update tasks by task_id (8 - char) or by matching task_info substring { name, match, state?, task_info?, parent_id?, extra_note?, comment? }. Creates a commit when changes occur; returns hash.
  • Lock rules: When a task (or any ancestor) is completed or archived, no edits are allowed to that task or its descendants, except unlocking the task itself to pending or in_progress (and only if none of its ancestors are locked). Unlocking a parent propagates to its descendants.
• generate_task_ids: Generate N unique 8 - character IDs not used by this user { count? } (default 5). Returns { ids: ["abcd1234", ...] }.
• get_agents_md_best_practices_and_examples: Returns best practices and examples from example_agent_md.json. Default returns only the_art_of_writing_agents_md (best - practices). Use include = 'all' to include all examples, or set include to a string/array to filter by usecase/title.
• list_project_logs: List commit logs { name } → { logs: [{ hash, message, modified_by, created_at }] }. The modified_by field shows who made each commit.
• revert_project: Revert to an earlier hash { name, hash }. Shared participants can only revert to commits in their most recent consecutive sequence (to prevent discarding others' work). Trims history to that point (no branches).

Scratchpad Tools

• scratchpad_initialize: Start a new scratchpad for a one - off task { name, tasks }. The server generates and returns a random scratchpad_id. tasks is up to 6 items { task_id, status: 'open'|'complete', task_info, scratchpad?, comments? }. Returns { scratchpad_id, project_id, tasks, common_memory }.
• review_scratchpad: Review a scratchpad by { name, scratchpad_id, IncludeCM?, IncludeTk? }.
  • IncludeCM: boolean; when true, include common_memory in the output.
  • IncludeTk: array of strings; filters tasks by task_id (case - insensitive exact) or task_info (case - insensitive substring). When provided, only matching tasks are returned.
  • If neither IncludeCM nor IncludeTk is provided, returns both tasks and common_memory (backwards - compatible default). Otherwise, includes only the requested fields; if IncludeTk is omitted, no tasks are returned.
• scratchpad_update_task: Update existing scratchpad tasks by task_id { name, scratchpad_id, updates }, where updates is an array of { task_id, status?, task_info?, scratchpad?, comments? }. Returns { updated, notFound, scratchpad }.
• scratchpad_append_common_memory: Append to the scratchpad’s shared memory { name, scratchpad_id, append } where append is a string or array of strings. Returns the updated scratchpad.

External AI Subagent Tools

• scratchpad_subagent: Start a subagent to work on a scratchpad task { name, scratchpad_id, task_id, prompt, sys_prompt?, tool? }. Tools depend on provider (AI_API_TYPE). Canonical tools: grounding (search), crawling (web fetch), code_execution (run code). Auto - appends common_memory to the prompt. May return early with status: in_progress and a run_id.
• scratchpad_subagent_status: Check run status { name, run_id }. Returns final status, or polls for up to ~25s when still running.

🔧 Technical Details

Providers and models

Examples (.env):

# Gemini
AI_API_TYPE=google
AI_MODEL="gemini-2.5-pro"

# OpenAI
# AI_API_TYPE=openai
# AI_MODEL="gpt-5-mini"

# Groq
# AI_API_TYPE=groq
# AI_MODEL="openai/gpt-oss-120b"

# OpenAI - compatible (e.g., LM Studio)
# AI_API_TYPE=compat
# AI_BASE_ENDPOINT="http://localhost:1234/v1"
# AI_MODEL="qwen/qwen3-4b-2507"

# MCP + OpenAI - compatible
# AI_API_TYPE=mcp
# AI_BASE_ENDPOINT="http://localhost:1234/v1"
# AI_MODEL="qwen/qwen3-4b-2507"

MCP provider configuration:

• Put MCP client config in subagent_config.json at the repo root. An example is included in this repo.
• Define servers under mcpServers. For remote servers use { "serverUrl": "https://.../mcp" } (HTTP) or .../sse (SSE; legacy but supported). For local stdio servers use { "command": "...", "args": [ ... ] }.
• Add a short one - line short_descriptions per server to help the agent choose (recommended). See the repo’s subagent_config.json for a minimal example.

📄 License

This project is licensed under the MIT License. See LICENSE for details.