Skip to main content
Glama
MickaelV0

demo-mcp

by MickaelV0
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

demo-mcp

Private shared memory POC for the Silex talk MCP + second cerveau: OKF markdown notes + links (optional human summary). Same brain via web UI and MCP (read + write).

Auth: shared API key (Authorization: Bearer … or X-API-Key).
Rate limit: 3 adds / min and 3 modifications / min per IP.

What you can share

Kind

Format

Rules

Note

Markdown + Open Knowledge Format frontmatter

type required; optional title, description, resource, tags, timestamp

Link

URL ± title ± tags ± summary

Summary is human-only (never server-generated). List needs_summary to contribute.

Notes are vectorized (when Workers AI + Vectorize are bound). Links are vectorized only if a summary is present.

Related MCP server: Bruin

Monorepo

apps/api          Hono Worker — REST + MCP + D1 + (optional) Vectorize/AI
apps/web          TanStack Router + React Query — private UI R/W
packages/shared   OKF parser/validator + Zod schemas
plugins/demo-mcp  Claude Code plugin (MCP + skills)
.claude-plugin/   Marketplace manifest (install from this repo)

Claude Code plugin

MCP alone = tools. Plugin = MCP + skills (when/how to use OKF, no auto-summaries, rate limits).

claude plugin marketplace add MickaelV0/demo-mcp
claude plugin install demo-mcp@demo-mcp
# prompts for API key (sensitive userConfig)

Local:

claude --plugin-dir ./plugins/demo-mcp

See plugins/demo-mcp/README.md.

Quick start

bun install

# Local API key — without it every /api/* and /mcp call returns 503
cp apps/api/.dev.vars.example apps/api/.dev.vars

# API (D1 local)
bun run dev:api
# → http://127.0.0.1:8787

# Web (proxies /api + /mcp to 8787)
bun run dev:web
# → http://127.0.0.1:5173

Apply local D1 migrations (first run / after schema change):

bun run db:migrate:local

Examples below use the .dev.vars.example key (dev-local-key). Every /api/* and /mcp call needs it — Authorization: Bearer … or X-API-Key.

Example: publish a note

curl -s http://127.0.0.1:8787/api/notes \
  -H 'authorization: Bearer dev-local-key' \
  -H 'content-type: text/markdown' \
  --data-binary @- <<'MD'
---
type: Note
title: Hello shared memory
tags: [demo, mcp]
---

Body in markdown. Link [[other]] or [x](./other.md).
MD

Example: link without summary

curl -s http://127.0.0.1:8787/api/links \
  -H 'authorization: Bearer dev-local-key' \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com","tags":["reading"]}'

MCP

claude mcp add demo-mcp --transport http http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer dev-local-key"

POST /mcp JSON-RPC: initialize, tools/list, tools/call.

REST map

Method

Path

Bucket

GET

/api/notes, /api/notes/:id

—

POST

/api/notes (OKF MD)

add

PUT

/api/notes/:id

mod

POST

/api/notes/:id/edges

add

GET

/api/links?needs_summary=1

—

POST

/api/links

add

PATCH

/api/links/:id/summary

mod

GET

/api/search?q=

—

GET

/api/tags

—

POST

/mcp

tools write → same buckets

Production

URL: https://demo-mcp.roxabi.dev
(same origin: SPA + /api/* + POST /mcp)

Deploy (CF credentials in shell only — never commit .env):

export CLOUDFLARE_ACCOUNT_ID=b5e90be971920ce406f7b679c4f1cd33

bun install
bun --filter @demo-mcp/web build
bunx wrangler d1 migrations apply demo-mcp --remote --config apps/api/wrangler.toml
# set once (or rotate): do NOT put this in the repo
printf '%s' "$DEMO_MCP_API_KEY" | bunx wrangler secret put API_KEY --config apps/api/wrangler.toml
bunx wrangler deploy --config apps/api/wrangler.toml

Public without key: GET /health only. All /api/* and /mcp need the key.

Optional embeddings: create Vectorize index, uncomment [[vectorize]] in apps/api/wrangler.toml, redeploy.

Design notes

  • POC auth — one shared API key (Worker secret API_KEY), not full user accounts.

  • No .env in repo — wrangler.toml [vars] for public config; secrets via wrangler secret put.

  • OKF only for notes — invalid frontmatter → 400.

  • Double surface — web curation + MCP action, one Hono API.

  • Context: Silex talk MCP, plugins & second cerveau.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Bruin

    sawzhang
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for AI agents to read, write, and organize notes in a local-first, human-in-the-loop note-taking app.
    4 npm
    2
    MIT

  • Cortex

    pixlflip
    A
    license
    Not graded
    quality
    B
    maintenance
    A dynamic, governed memory layer for Markdown notes that serves knowledge to AI clients and humans through a secure MCP server, with scoped access, git-audited changes, and optional LLM-powered semantic search.
    Apache 2.0

  • Zero Brain MCP Server

    miru-zero
    A
    license
    A
    quality
    A
    maintenance
    MCP server for managing a local, domain-agnostic knowledge base using Markdown notes with frontmatter. Enables AI agents to capture, read, search, link, and maintain notes with atomic writes and privacy controls.
    13
    MIT