Agents.md


Architecture Overview

This project implements a hierarchical context management system for AI agents working on long-term projects, so that:

- 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

Automatic Install and User creation (Unix-like systems)

- Without docker: (Install to $HOME/.config/mcp-http-agent-md and start with a default user)
``bash
curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install.sh | bash
`
- With docker: (Data persist in $HOME/.config/mcp-http-agent-md/data)
`bash
curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install-docker.sh | bash
`

Manual Install

First, clone the repo: git clone https://github.com/benhaotang/mcp-http-agent-md.git

Environments

You can set all Environments defined in .env.example in Terminal via export XXX=xxx.

If you prefer setting them via .env: 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. Learn more about supported Providers and models.
`
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
`

> [!NOTE]
> For docker, we currently only support adding them via -e XXX=xxx for security. If you want to use .env file, remove it from .dockerignore and build the image locally. See Docker.

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

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 .

Endpoints

- Admin API: http://localhost:3000/auth (Bearer MAIN_API_KEY), generate a USER_API_KEY first, see Auth
- MCP endpoint: POST http://localhost:3000/mcp?apiKey=USER_API_KEY
- Local
`json
{
"mcpServers": {
"mcp-agent-md": {
"command": "npx",
"args": ["-y","mcp-remote","http://localhost:3000/mcp?apiKey=USER_API_KEY"]
}
}
}
``
- Remote
`json
{
"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"}'
`

Definition

Base: /auth (Bearer MAIN_API_KEY)
- POST /auth/users: Create user → { id, apiKey, name? }
- GET /auth/users: List users (?reveal=true to show full keys)
- GET /auth/users/:id: Get user
- POST /auth/users/:id/regenerate: Rotate API key
- DELETE /auth/users/:id`: Delete user