ark

About

ark is a fork of Inkstone, a browser-based Markdown notebook that runs entirely on Cloudflare Workers (D1, R2, Durable Objects). ark keeps everything Inkstone does — editor, wiki links, backlinks, graph, FTS5 search, versions, sync, backups — and adds a stateless MCP surface so LLM agents become first-class users of the vault.

The goal is the Karpathy-style LLM-Wiki pattern in the cloud: raw sources are ingested, compiled by agents into wiki pages with indexes and cross-links, then queried during research — with the vault reachable from any machine, not just where the files live.

Related MCP server: docs-to-mcp

The MCP surface

ark mounts an MCP endpoint at /mcp, implementing spec revision 2026-07-28 (fully stateless: no initialize handshake, no session ids) plus a dual-era shim that answers the legacy initialize handshake so current MCP clients connect today.

• Auth: personal access tokens (ak_…), minted by the owner, stored as SHA-256 hashes in D1 with per-token scopes and optional expiry.

• Transport: single JSON-RPC POST endpoint; validates MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers against the body (spec error -32020), negotiates versions (-32022), answers server/discover, and serves cacheable tools/list results (ttlMs/cacheScope).

• Tools (walking skeleton): search_wiki — ranked FTS5 snippets scoped to the token's user. The query string supports tag:name, folder:name, is:starred, is:archived, in:trash, and "quoted phrases". Read tools, write tools with MRTR, lint, and semantic search are planned.

Authentication

ark signs users in with Google OAuth only. Password login and registration are disabled everywhere except local development.

Enable Google sign-in (production)

1. In Google Cloud Console, create an OAuth client ID of type Web application with the authorized redirect URI https://YOUR-WORKER/api/auth/google/callback.

2. Configure the Worker:

npx wrangler secret put GOOGLE_CLIENT_SECRET

And in wrangler.toml under [vars]:

GOOGLE_CLIENT_ID = "…apps.googleusercontent.com"
GOOGLE_ALLOWED_EMAILS = "you@example.com"

Only the Google accounts in GOOGLE_ALLOWED_EMAILS (comma-separated, case-insensitive) can sign in; everyone signs into the owner's vault. If no owner account exists yet, the first allowed Google sign-in creates it.

Local dev mode (password auth, local only)

Create a .dev.vars file (gitignored, read only by wrangler dev / vite — never deployed):

AUTH_DEV_MODE=1

With it, classic username/password register/login work locally for testing. Without it — i.e. in every deployment — password endpoints return 403 password_auth_disabled.

Mint an MCP token

In production: sign in with Google in the browser, then run this in the devtools console:

await fetch('/api/mcp-tokens', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Ark-Client': '1' },
  body: JSON.stringify({ label: 'my-agent', ttlDays: 365 }),
}).then((r) => r.json())

In local dev mode the same endpoint works with a password session:

curl -s -c jar http://localhost:8787/api/auth/login \
  -H 'Content-Type: application/json' -H 'X-Ark-Client: 1' \
  -d '{"username":"you","password":"…"}'

curl -s -b jar http://localhost:8787/api/mcp-tokens -X POST \
  -H 'Content-Type: application/json' -H 'X-Ark-Client: 1' \
  -d '{"label":"my-agent"}'

The plaintext token is returned exactly once.

Connect Claude Code

claude mcp add --transport http ark https://YOUR-WORKER/mcp \
  --header "Authorization: Bearer ak_…"

Call it raw (2026-07-28 strict mode)

curl -s https://YOUR-WORKER/mcp \
  -H "Authorization: Bearer ak_…" -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: tools/call' -H 'Mcp-Name: search_wiki' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_wiki","arguments":{"query":"tag:research \"exact phrase\""},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Inherited features

Data storage

Deployment

1. Fork this repository to your GitHub account.

2. Open Cloudflare Workers & Pages and connect the fork, or run npm run deploy locally with wrangler authenticated.

3. Configure Google sign-in (see Authentication) and open the deployed URL.

4. Mint an MCP token and connect your agent.

Note: the schema initializer asserts the final schema and does not run migrations. If you upgrade an existing deployment across a schema change, apply the new DDL manually with wrangler d1 execute (see src/worker/db/schema.ts).

Development and verification

Requires Node ^24.15.0.

Repository layout

src/
├── client/   React interface, editor, preview, and local state
├── shared/   Shared types, limits, locale resources, and Markdown utilities
└── worker/   Hono API, authentication, D1 access, sync, sharing, backups,
              and the MCP surface (src/worker/mcp/)
public/       Static assets
scripts/      Repository checks and end-to-end verification scripts
tests/        Cross-module regression tests

Security and contributions

Read SECURITY.md before reporting a vulnerability. Development setup and contribution requirements are documented in CONTRIBUTING.md.

Credits and license

ark is created and maintained by Ricardo Ruiz (@ruizrica).

It is a derivative work of Inkstone by shuaiplus, distributed under the GNU Lesser General Public License v3.0 only (LGPL-3.0-only). ark keeps the same license.