guanling (關令)

A task-management MCP server that refuses.

Most task tools do what you tell them. This one has opinions and enforces them.

Why this exists

A real task list grew to 280 items. Sixteen were marked "in progress". Not one of them was actually being worked on.

The missing thing was not a tool — there already was a list. The missing thing was anything that forced a decision. Every operation said yes, so the list accumulated intentions and never spent them.

What makes Linear work is not its feature set. It is its refusals: a small fixed set of states you cannot extend, and limits you cannot argue with. This server copies the refusals, not the features.

Related MCP server: todo-mcp

The gates

Each one is a refusal, not a warning.

Refused calls write nothing to disk — there is a test for this.

Install

npm install -g guanling

Then add it to your MCP client config:

{
  "mcpServers": {
    "guanling": {
      "command": "npx",
      "args": ["-y", "guanling"],
      "env": {
        "GUANLING_AGENT": "me",
        "GUANLING_FILE": "/path/to/my-tasks.json",
        "GUANLING_WIP": "3"
      }
    }
  }
}

⚠️ Give every instance its own GUANLING_FILE. Two processes sharing one file will overwrite each other — see Limitations.

Tools

Storage

One JSON file, written atomically (write to a temp file, then rename).

Deliberately not a database. The scale is hundreds of rows, and a plain file stays readable by a human, diffable in git, and backed up by cp. The complete string is built before the file is opened, so an exception mid-serialisation leaves the previous file intact.

Tests

node selftest.mjs

16 arms, weighted toward the refusals — those are the product. Includes a negative control asserting that a rejected task_add leaves nothing on disk.

The WIP gate is mutation-tested: removing it turns exactly the two arms that cover it red. A gate that cannot be observed failing has not been verified.

Limitations

Stated up front rather than discovered later.

• No concurrency lock. One process per store file. Two writers will clobber each other.

• No cross-instance visibility. Each instance sees only its own file. This is intentional for per-agent isolation, but it means separate agents cannot see each other's work and may duplicate effort.

• snooze sets snooze_until but nothing wakes it. Items do not return on their own; task_list is how you find them.

• No history or audit trail. The file holds current state only.

The name

關令尹喜 was the gatekeeper at Hangu Pass. When Laozi tried to leave through it, the gatekeeper would not let him pass until he wrote his teaching down — which is why the Tao Te Ching exists.

Same idea: you do not get through until you write it down.

Privacy Policy

What is collected: nothing. Guanling has no telemetry, no analytics, no crash reporting, and no update check.

What is stored, and where: only the tasks you create — their title, owner, next step, status, optional source and blocker, timestamps, and close reason. They are written to a single JSON file on your own machine, at the path you configure (GUANLING_FILE, or ~/.guanling/<agent>.json by default). Nothing is written anywhere else.

Third-party sharing: none. The server makes no network requests of any kind — it has no HTTP client, no sockets, and no dependencies beyond two Node builtins (node:fs and node:path). It communicates only over stdio with the MCP client that launched it. Its network behaviour is verifiable by reading server.mjs, which is short and has no imports other than those two.

Data retention: entirely yours. The file persists until you delete it. Guanling never expires, prunes, or deletes data on its own — closing a task marks it done or dropped and keeps the record. To erase everything, delete the JSON file.

Your control: the store is plain JSON. You can read it, edit it, copy it, back it up, or delete it with ordinary file tools. No export feature is needed because the file is the export.

Contact: open an issue at https://github.com/fateLiang/guanling/issues.

License

MIT