Why Metakip?

Metakip is an open-source, markdown-based knowledge base for humans and their AI agents. It is currently available in public beta at metakip.com and can also be self-hosted under the GNU AGPL v3.

The important idea is that the browser, CLI, REST API, and MCP interface all use the same content layer. A page created by a person is the same kind of page an agent can read, edit, and link to. There is no separate agent mode, data store, or sync layer to keep in agreement.

What's Unique About This?

The API is the product, not an adapter bolted onto a human-only app.

Metakip treats AI agents as first-class users. Agents can work with the same pages and folders as people through the REST API, the terminal CLI, or remote MCP. Access is permissioned: read-only tokens are suitable for answering questions, while write access can be granted when an agent needs to create or make targeted edits.

The product also keeps the parts that make a knowledge base useful for people: markdown editing, folders, backlinks, tags, search, sharing, and real-time collaboration.

Architecture

Monorepo Structure

packages/
├── api/       # Hono API and PostgreSQL persistence
├── web/       # React/Vite application and Markdown editor
├── collab/    # Hocuspocus collaboration service
├── mcp/       # Remote MCP server and API client
├── shared/    # Shared types and utilities
└── marketing-site/ # Public landing page

Backend

API: Hono with regular browser routes and a versioned /api/v1 contract
Database: PostgreSQL with Drizzle ORM
Authentication: Better Auth, OAuth, scoped API tokens, and MCP OAuth
Content: Markdown converted to and from Yjs documents, with page metadata, folders, links, sharing, versions, search, imports, exports, and Trash

Frontend

Framework: React with Vite and React Router
Editor: CodeMirror with CommonMark/GFM support, math, tables, task lists, callouts, wiki links, slash commands, and collaborative cursors
Data fetching: TanStack Query
UI: Tailwind CSS with a responsive interface and dark mode

Collaboration And Agents

Real-time editing: Yjs CRDTs over Hocuspocus WebSockets
Sharing: Restricted pages, public view/edit links, and per-person view/edit/admin access
CLI: Page search, reading, creation, exact edits, Markdown import/export, workspace export, and an installable agent skill
MCP: OAuth-protected tools for searching, reading, creating, updating, moving, copying, importing, exporting, and managing pages and folders

Learnings

Since building Metakip, I learned:

How to design a product where humans and agents share one content layer
Building a real-time collaborative editor around Yjs and Hocuspocus
Designing versioned REST APIs for both interactive clients and automation
Integrating MCP and OAuth without bypassing normal workspace permissions
Building reliable Markdown and Obsidian import/export workflows
Structuring a TypeScript monorepo with separate web, API, collaboration, MCP, shared, documentation, and marketing packages
Deploying and documenting an open-source application for self-hosting

Metakip

Year

Status

Tech Stack

Links

Contents