ki-manager 2.0.16

Knowledge Item (KI) management MCP server for AI-assisted development

ki-manager — Knowledge Item MCP Server

AI-powered knowledge management for software projects.
Install once, use across all your projects.

---

What is ki-manager?

ki-manager is an MCP (Model Context Protocol) server that turns any project into a self-documenting codebase for AI agents (Claude, Antigravity, Cursor, Windsurf, etc.).

It provides:

• Knowledge Items (KI) — structured Markdown snapshots of each module, stored in .ki-base/knowledge/
• Coverage Audit — measures how well your KI base covers your actual code
• Dependency Analysis — auto-updates "Related KIs" by analyzing imports
• Git Snapshots — versioned knowledge state (git_checkpoint, git_restore)
• Scaffolding — one command creates the complete .ki-base/ structure in any project

---

Installation

Option A: uvx (recommended — no install needed)

{
  "mcpServers": {
    "ki-manager": {
      "command": "uvx",
      "args": ["--quiet", "ki-manager"]
    }
  }
}

Requires uv — install with: curl -LsSf https://astral.sh/uv/install.sh | sh
First run: uvx downloads and caches the package automatically. Subsequent launches are instant.

Option B: Smithery (Claude Desktop / Cursor / Windsurf GUI)

Search for ki-manager in your IDE's MCP marketplace and click Install.

Option C: pip

pip install ki-manager
ki-manager  # starts the MCP server

Option D: Local development

If you cloned the repository and are developing locally, point your IDE to the .venv Python directly:

{
  "mcpServers": {
    "ki-manager": {
      "command": "/absolute/path/to/repo/.venv/bin/python",
      "args": ["-m", "ki_manager.server"]
    }
  }
}

On Windows:

{
  "mcpServers": {
    "ki-manager": {
      "command": "C:\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ki_manager.server"]
    }
  }
}

---

Quickstart

1. Add the MCP server to your IDE

Pick one of the options above and add it to your MCP config.

2. Initialize a project

In your IDE chat, call the ki_init_project tool:

ki_init_project(project_path="/absolute/path/to/your-project")

This creates:

your-project/
└── .ki-base/
    ├── config.json          ← machine-specific (auto-added to .gitignore)
    ├── ki_config.json       ← project settings (commit to git)
    ├── doc_config.json      ← file→KI map (commit to git)
    ├── AGENTS.md            ← agent instructions (commit to git)
    ├── DIR_INDEX.md         ← directory index (commit to git)
    └── knowledge/
        └── _OVERVIEW.ki.md  ← starter Knowledge Item

3. Start documenting

Use the available tools or slash commands:

Tool / Command	Action
audit_coverage	Find documentation gaps
generate_dir_index	Build directory index
sync_agents_md	Sync KI table in AGENTS.md
git_checkpoint	Save knowledge snapshot to git
/expand-knowledge	Iteratively fill gaps (Antigravity)
/sync-knowledge	Full sync workflow (Antigravity)
/create-adr	Record architectural decision

---

What Goes Into Git?

Path	Git	Notes
.ki-base/knowledge/*.ki.md	✅	Project knowledge
.ki-base/doc_config.json	✅	Module manifest
.ki-base/ki_config.json	✅	Project settings
.ki-base/AGENTS.md	✅	Agent instructions
.ki-base/DIR_INDEX.md	✅	Directory index
.ki-base/config.json	❌	Machine-specific paths
.ki-base/doc_state.json	❌	Hash cache

---

Security

The MCP server operates in a sandbox:

• All file access is restricted to the .ki-base/ directory
• Executable files (.py, .exe, .sh, etc.) cannot be modified via MCP
• Critical config files are protected from direct overwrite

---

Project Structure (this repo)

ki-manager/
├── pyproject.toml            ← pip / uvx package config
├── smithery.yaml             ← Smithery MCP marketplace config
├── src/ki_manager/
│   ├── server.py             ← MCP server entry point
│   ├── tools/
│   │   └── scaffold.py       ← ki_init_project implementation
│   └── scripts/              ← bundled analysis scripts
│       ├── ki_utils.py       ← shared utilities
│       ├── audit_coverage.py
│       ├── sync_agents_md.py
│       ├── generate_dir_index.py
│       ├── ki_dependency_analyzer.py
│       └── ...
├── knowledge/                ← KI documentation of this repo itself
└── decisions/                ← Architecture Decision Records

---

Troubleshooting

MCP server hangs on initialization (never connects)

This is the most common issue on Windows and affects both uvx and direct python launches.

Step 1 — Check logs:
Server logs are written to ~/.ki_base/logs/. Open the latest file and look for REQ: lines. If there are no REQ: lines at all, stdin is not being piped correctly by the IDE.

Step 2 — Try the local Python fallback:
Replace uvx with the absolute path to .venv/Scripts/python.exe (Windows) or .venv/bin/python (Linux/macOS) to rule out uvx as the cause:

{
  "mcpServers": {
    "ki-manager": {
      "command": "C:\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ki_manager.server"]
    }
  }
}

Step 3 — Refresh the uvx cache:
If a new version was published to PyPI, uvx may be running a stale cached version. Force a refresh by running this once in a terminal:

uvx --refresh ki-manager

(Press Ctrl+C after it starts — you just need it to update the cache, not keep running.)

Server is running but no tools appear

Check that ki_status is visible in the IDE. If it shows No project active for current workspace, the server is working correctly — it just needs a project to be initialized (ki_init_project) or the IDE is not passing rootUri in the MCP handshake.

[Errno 22] Invalid argument in logs

This error was present in versions < 2.0.11 on Windows when wrapping sys.stdout with a codecs encoder. Upgrade to >= 2.0.11 to fix it:

uvx --refresh ki-manager

---

License

MIT — free to use, copy, and adapt.