okfshare CLI and MCP server

Client-side, open-source half of okfshare: shared, versioned knowledge for AI coding agents.

Publish a validated bundle of Markdown once. Every authorized agent works from the same immutable revision, with line-level citations you can audit. The hosted service keeps revisions, citations, and workspace auth; this repo holds the tools your agents actually run.

Packages

Related MCP server: okf-mcp

Quick start

# 1. One-time onboarding (device pairing in your browser)
npx okfshare@latest setup

# 2. Validate and publish a folder of Markdown
npx okfshare@latest validate ./knowledge
npx okfshare@latest publish ./knowledge --visibility public --yes

# 3. Any teammate's agent retrieves cited context
npx okfshare@latest context SHARE_ID "how do we handle db migrations"

Headless/CI environments: supply a pre-provisioned credential via the OKFSHARE_TOKEN environment variable (check existence only; never log it), then verify with whoami and doctor.

MCP setup

claude mcp add okfshare -- npx @okfshare/mcp@latest

Or any MCP client:

{
  "mcpServers": {
    "okfshare": {
      "command": "npx",
      "args": ["@okfshare/mcp@latest"]
    }
  }
}

Tools: whoami, doctor, list_shares, search_share, search_workspace, get_context, pull_bundle, publish_bundle. Registry manifest: server.json.

Why citations matter

Retrieval returns the file, the exact lines, and the immutable revision they came from. When an agent claims "our convention says X", you can audit the claim in seconds - and a citation means the same thing tomorrow, because revision content never changes in place.

The Open Knowledge Format

Bundles are Markdown with structured frontmatter: a type, title, description, tags, sources, and verification events. The format is deliberately small and stays readable in any editor. Worst case, you are left with plain files - no lock-in.

• Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

• Field guide (published with okfshare itself): https://okfshare.app/s/ecf08367a22273482c0887ca8700ee8e

• Forkable conventions starter: https://okfshare.app/s/e8ddeda5aab619495c970f031dce7058

Development

pnpm install
pnpm check   # typecheck + test + build across all packages

• Node 20+ and pnpm 10.

• The packages talk to the hosted API at https://okfshare.app; no local server is required to develop them.

• See CONTRIBUTING.md for the acceptance flow and SECURITY.md for reporting vulnerabilities.

Links

• Site and docs: https://okfshare.app

• Agent-readable docs: https://okfshare.app/llms.txt and https://okfshare.app/llms-full.txt

License

Apache-2.0. See NOTICE - the code license does not grant rights to the okfshare name or branding.