okfy-ai 0.1.2

package/examples/README.md

@@ -0,0 +1,98 @@
+# Examples
+
+## bundles/okfy-docs
+
+Purpose: committed offline OKF bundle used by `okfy demo`.
+
+Source command:
+
+```bash
+pnpm okfy import examples/local-markdown --out examples/bundles/okfy-docs --source-name "okfy docs" --force --stable-timestamps
+```
+
+Expected concept count:
+
+```text
+9
+```
+
+Expected validation status:
+
+```text
+valid
+```
+
+Suggested agent questions:
+
+- Search for crawler security defaults, read the relevant concepts, and cite the source resource.
+- Read the MCP setup concept and explain the stdio config.
+- Find importer concepts and list supported input formats.
+
+## bundles/stripe-checkout-small
+
+Purpose: small curated Stripe Checkout sample for launch demos when live crawling is flaky.
+
+Source command:
+
+```bash
+pnpm okfy import test-fixtures/stripe-checkout-html --out examples/bundles/stripe-checkout-small --source-name "Stripe Checkout sample" --force --stable-timestamps
+```
+
+Expected concept count:
+
+```text
+4
+```
+
+Expected validation status:
+
+```text
+valid
+```
+
+Suggested agent questions:
+
+- Search for Checkout Sessions, read the strongest match, and explain required server parameters.
+- Find webhook-related concepts and summarize fulfillment safety notes.
+- Use neighbors to move from the quickstart to the API reference and webhook concepts.
+
+## local-markdown
+
+Purpose: deterministic offline input for `okfy import`.
+
+Source command:
+
+```bash
+npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force --stable-timestamps
+```
+
+Expected concept count:
+
+```text
+9
+```
+
+Expected validation status:
+
+```text
+valid
+```
+
+Validate:
+
+```bash
+npx -y okfy-ai validate ./tmp/okfy-docs
+npx -y okfy-ai inspect ./tmp/okfy-docs
+```
+
+Serve through MCP:
+
+```bash
+npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+```
+
+Suggested agent questions:
+
+- Search for import workflow concepts, read the best match, and explain how to convert a local Markdown folder into OKF.
+- Find concepts tagged `mcp`, read the MCP tools concept, and describe the expected tool-call sequence.
+- Read the bundle summary, then identify which concepts are most useful for a first-time okfy user.

package/examples/bundles/okfy-docs/concepts/index.md

@@ -0,0 +1,14 @@
+---
+type: "Folder Index"
+title: "Concepts Index"
+description: "Index for concepts."
+resource: "okfy docs"
+tags:
+  - "index"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+
+# Concepts Index
+
+- [okf-bundle](./okf-bundle.md)
+- [progressive-disclosure](./progressive-disclosure.md)

package/examples/bundles/okfy-docs/concepts/okf-bundle.md

@@ -0,0 +1,33 @@
+---
+type: "Concept"
+title: "OKF Bundle Structure"
+description: "An Open Knowledge Format bundle is a directory of Markdown files with YAML frontmatter. Minimum valid concept: Useful generated fields include title, description, resource, tags, a"
+resource: "concepts/okf-bundle.md"
+tags:
+  - "concepts"
+  - "okf"
+  - "bundle"
+  - "structure"
+  - "concept"
+  - "title"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# OKF Bundle Structure
+
+An Open Knowledge Format bundle is a directory of Markdown files with YAML frontmatter.
+
+Minimum valid concept:
+
+```md
+---
+type: Concept
+---
+
+# Concept title
+```
+
+Useful generated fields include `title`, `description`, `resource`, `tags`, and `timestamp`.
+
+okfy keeps output file-based so humans can inspect it, Git can diff it, and MCP clients can read only the concepts they need.
+
+Related: [Progressive Disclosure](./progressive-disclosure.md).

package/examples/bundles/okfy-docs/concepts/progressive-disclosure.md

@@ -0,0 +1,26 @@
+---
+type: "Documentation Page"
+title: "Progressive Disclosure"
+description: "Progressive disclosure means an agent starts with small previews and only loads full concept content when needed. For okfy, the default pattern is: This keeps prompt context smalle"
+resource: "concepts/progressive-disclosure.md"
+tags:
+  - "concepts"
+  - "progressive"
+  - "disclosure"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Progressive Disclosure
+
+Progressive disclosure means an agent starts with small previews and only loads full concept content when needed.
+
+For okfy, the default pattern is:
+
+```text
+search_concepts returns bounded previews
+read_concept returns one concept
+get_neighbors returns linked context
+```
+
+This keeps prompt context smaller than pasting full docs or loading an entire Markdown folder.
+
+Related: [Serve Over MCP](../guides/serve-over-mcp.md).

package/examples/bundles/okfy-docs/guides/import-local-markdown.md

@@ -0,0 +1,31 @@
+---
+type: "Documentation Page"
+title: "Import Local Markdown"
+description: "Use okfy import when docs already live in a local project checkout, wiki export, Obsidian vault, or staticsite source folder. Expected result: The importer preserves headings, code"
+resource: "guides/import-local-markdown.md"
+tags:
+  - "guides"
+  - "import"
+  - "local"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Import Local Markdown
+
+Use `okfy import` when docs already live in a local project checkout, wiki export, Obsidian vault, or static-site source folder.
+
+```bash
+npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force
+npx -y okfy-ai validate ./tmp/okfy-docs
+```
+
+Expected result:
+
+```text
+Concepts: 6
+Validation: valid
+Broken links: 0
+```
+
+The importer preserves headings, code blocks, and Markdown links. It infers tags from paths and headings, then writes one OKF concept per input file.
+
+Next: [Serve Over MCP](./serve-over-mcp.md).

package/examples/bundles/okfy-docs/guides/index.md

@@ -0,0 +1,14 @@
+---
+type: "Folder Index"
+title: "Guides Index"
+description: "Index for guides."
+resource: "okfy docs"
+tags:
+  - "index"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+
+# Guides Index
+
+- [import-local-markdown](./import-local-markdown.md)
+- [serve-over-mcp](./serve-over-mcp.md)

package/examples/bundles/okfy-docs/guides/serve-over-mcp.md

@@ -0,0 +1,29 @@
+---
+type: "API Reference"
+title: "Serve Over MCP"
+description: "After generating an OKF bundle, serve it over stdio MCP: Agents should not read the whole bundle first. The efficient flow is: Use searchconcepts for discovery, readconcept for gro"
+resource: "guides/serve-over-mcp.md"
+tags:
+  - "guides"
+  - "serve"
+  - "over"
+  - "mcp"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Serve Over MCP
+
+After generating an OKF bundle, serve it over stdio MCP:
+
+```bash
+npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+```
+
+Agents should not read the whole bundle first. The efficient flow is:
+
+```text
+bundle_summary -> search_concepts -> read_concept -> get_neighbors -> answer
+```
+
+Use `search_concepts` for discovery, `read_concept` for grounded detail, and `get_neighbors` when linked concepts may change the answer.
+
+See [MCP tools](../reference/mcp-tools.md) for tool descriptions.

package/examples/bundles/okfy-docs/index.md

@@ -0,0 +1,22 @@
+---
+type: "API Reference"
+title: "okfy Local Markdown Fixture"
+description: "This fixture models a small docs folder that can be imported into OKF without network access. Start with Import Local Markdown, then read Serve Over MCP. Key topics: OKF bundle str"
+resource: "index.md"
+tags:
+  - "okfy"
+  - "local"
+  - "fixture"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# okfy Local Markdown Fixture
+
+This fixture models a small docs folder that can be imported into OKF without network access.
+
+Start with [Import Local Markdown](./guides/import-local-markdown.md), then read [Serve Over MCP](./guides/serve-over-mcp.md).
+
+Key topics:
+
+- [OKF bundle structure](./concepts/okf-bundle.md)
+- [Progressive disclosure](./concepts/progressive-disclosure.md)
+- [MCP tools](./reference/mcp-tools.md)

package/examples/bundles/okfy-docs/okfy-example.json

@@ -0,0 +1,10 @@
+{
+  "sourceCommand": "pnpm okfy import examples/local-markdown --out examples/bundles/okfy-docs --source-name \"okfy docs\" --force --stable-timestamps",
+  "expectedConceptCount": 9,
+  "expectedValidationStatus": "valid",
+  "suggestedAgentQuestions": [
+    "Search okfy docs for crawler security defaults, then cite source concepts.",
+    "Read the MCP setup concept and explain the stdio config.",
+    "Find importer concepts and list supported input formats."
+  ]
+}

package/examples/bundles/okfy-docs/reference/index.md

@@ -0,0 +1,13 @@
+---
+type: "Folder Index"
+title: "Reference Index"
+description: "Index for reference."
+resource: "okfy docs"
+tags:
+  - "index"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+
+# Reference Index
+
+- [mcp-tools](./mcp-tools.md)

package/examples/bundles/okfy-docs/reference/mcp-tools.md

@@ -0,0 +1,36 @@
+---
+type: "API Reference"
+title: "MCP Tools"
+description: "okfy exposes these readonly MCP tools: | Tool | Purpose | | | | | searchconcepts | Find concept previews by query, type, or tags. | | readconcept | Read one concept body, frontmatt"
+resource: "reference/mcp-tools.md"
+tags:
+  - "reference"
+  - "mcp"
+  - "tools"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# MCP Tools
+
+okfy exposes these read-only MCP tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `search_concepts` | Find concept previews by query, type, or tags. |
+| `read_concept` | Read one concept body, frontmatter, links, backlinks, and source resource. |
+| `get_neighbors` | Traverse outbound links and backlinks around a concept. |
+| `list_types` | Show concept types and counts. |
+| `list_tags` | Show tags and counts. |
+| `bundle_summary` | Show bundle title, concept count, type distribution, connected concepts, and validation status. |
+
+Expected question-answer flow:
+
+```text
+bundle_summary
+search_concepts
+read_concept
+get_neighbors
+read_concept
+answer with citations
+```
+
+Related: [Progressive Disclosure](../concepts/progressive-disclosure.md).

package/examples/bundles/stripe-checkout-small/index.md

@@ -0,0 +1,21 @@
+---
+type: "API Reference"
+title: "Stripe Checkout"
+description: "Checkout is a prebuilt payment form for accepting cards and other payment methods. This saved fixture mirrors the launch demo shape without requiring network access. Checkout quick"
+resource: "index.html"
+tags:
+  - "stripe"
+  - "checkout"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Stripe Checkout
+
+Checkout is a prebuilt payment form for accepting cards and other payment methods.
+
+This saved fixture mirrors the launch demo shape without requiring network access.
+
+-   [Checkout quickstart](./quickstart.md)
+-   [Checkout Sessions API](./sessions.md)
+-   [Checkout webhooks](./webhooks.md)
+
+Original source: [https://docs.stripe.com/checkout](https://docs.stripe.com/checkout)

package/examples/bundles/stripe-checkout-small/okfy-example.json

@@ -0,0 +1,11 @@
+{
+  "sourceCommand": "pnpm okfy import test-fixtures/stripe-checkout-html --out examples/bundles/stripe-checkout-small --source-name \"Stripe Checkout sample\" --force --stable-timestamps",
+  "expectedConceptCount": 4,
+  "expectedValidationStatus": "valid",
+  "sampleNote": "Curated saved-HTML sample used when live crawling is flaky; source URLs are preserved in concept bodies and resource metadata points to the fixture source.",
+  "suggestedAgentQuestions": [
+    "Search for Checkout Sessions, read the strongest match, and explain required server parameters.",
+    "Find webhook-related concepts and summarize fulfillment safety notes.",
+    "Use neighbors to move from the quickstart to the API reference and webhook concepts."
+  ]
+}

package/examples/bundles/stripe-checkout-small/quickstart.md

@@ -0,0 +1,26 @@
+---
+type: "API Reference"
+title: "Checkout quickstart"
+description: "Create a server endpoint that creates a Checkout Session, then redirect the customer to the session URL. See Checkout Sessions API and Checkout webhooks. Original source: https://d"
+resource: "quickstart.html"
+tags:
+  - "quickstart"
+  - "checkout"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Checkout quickstart
+
+Create a server endpoint that creates a Checkout Session, then redirect the customer to the session URL.
+
+```
+const session = await stripe.checkout.sessions.create({
+  mode: "payment",
+  line_items: [{ price: "price_123", quantity: 1 }],
+  success_url: "https://example.com/success",
+  cancel_url: "https://example.com/cancel"
+});
+```
+
+See [Checkout Sessions API](./sessions.md) and [Checkout webhooks](./webhooks.md).
+
+Original source: [https://docs.stripe.com/checkout/quickstart](https://docs.stripe.com/checkout/quickstart)

package/examples/bundles/stripe-checkout-small/sessions.md

@@ -0,0 +1,20 @@
+---
+type: "API Reference"
+title: "Checkout Sessions API"
+description: "A Checkout Session represents a customer's session as they pay for onetime purchases or subscriptions. Important parameters include mode, lineitems, successurl, and cancelurl. Star"
+resource: "sessions.html"
+tags:
+  - "sessions"
+  - "checkout"
+  - "api"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Checkout Sessions API
+
+A Checkout Session represents a customer's session as they pay for one-time purchases or subscriptions.
+
+Important parameters include `mode`, `line_items`, `success_url`, and `cancel_url`.
+
+Start with the [Checkout quickstart](./quickstart.md).
+
+Original source: [https://docs.stripe.com/api/checkout/sessions](https://docs.stripe.com/api/checkout/sessions)

package/examples/bundles/stripe-checkout-small/webhooks.md

@@ -0,0 +1,19 @@
+---
+type: "API Reference"
+title: "Checkout webhooks"
+description: "Listen for checkout.session.completed before fulfilling orders or granting access. Webhook handlers should verify signatures and handle retries idempotently. Related: Checkout Sess"
+resource: "webhooks.html"
+tags:
+  - "webhooks"
+  - "checkout"
+timestamp: "2026-06-14T00:00:00.000Z"
+---
+# Checkout webhooks
+
+Listen for `checkout.session.completed` before fulfilling orders or granting access.
+
+Webhook handlers should verify signatures and handle retries idempotently.
+
+Related: [Checkout Sessions API](./sessions.md).
+
+Original source: [https://docs.stripe.com/checkout/fulfillment](https://docs.stripe.com/checkout/fulfillment)

package/examples/local-markdown/concepts/okf-bundle.md

@@ -0,0 +1,19 @@
+# OKF Bundle Structure
+
+An Open Knowledge Format bundle is a directory of Markdown files with YAML frontmatter.
+
+Minimum valid concept:
+
+```md
+---
+type: Concept
+---
+
+# Concept title
+```
+
+Useful generated fields include `title`, `description`, `resource`, `tags`, and `timestamp`.
+
+okfy keeps output file-based so humans can inspect it, Git can diff it, and MCP clients can read only the concepts they need.
+
+Related: [Progressive Disclosure](progressive-disclosure.md).

package/examples/local-markdown/concepts/progressive-disclosure.md

@@ -0,0 +1,15 @@
+# Progressive Disclosure
+
+Progressive disclosure means an agent starts with small previews and only loads full concept content when needed.
+
+For okfy, the default pattern is:
+
+```text
+search_concepts returns bounded previews
+read_concept returns one concept
+get_neighbors returns linked context
+```
+
+This keeps prompt context smaller than pasting full docs or loading an entire Markdown folder.
+
+Related: [Serve Over MCP](../guides/serve-over-mcp.md).

package/examples/local-markdown/guides/import-local-markdown.md

@@ -0,0 +1,20 @@
+# Import Local Markdown
+
+Use `okfy import` when docs already live in a local project checkout, wiki export, Obsidian vault, or static-site source folder.
+
+```bash
+npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force
+npx -y okfy-ai validate ./tmp/okfy-docs
+```
+
+Expected result:
+
+```text
+Concepts: 6
+Validation: valid
+Broken links: 0
+```
+
+The importer preserves headings, code blocks, and Markdown links. It infers tags from paths and headings, then writes one OKF concept per input file.
+
+Next: [Serve Over MCP](serve-over-mcp.md).

package/examples/local-markdown/guides/serve-over-mcp.md

@@ -0,0 +1,17 @@
+# Serve Over MCP
+
+After generating an OKF bundle, serve it over stdio MCP:
+
+```bash
+npx -y okfy-ai serve ./tmp/okfy-docs --mcp
+```
+
+Agents should not read the whole bundle first. The efficient flow is:
+
+```text
+bundle_summary -> search_concepts -> read_concept -> get_neighbors -> answer
+```
+
+Use `search_concepts` for discovery, `read_concept` for grounded detail, and `get_neighbors` when linked concepts may change the answer.
+
+See [MCP tools](../reference/mcp-tools.md) for tool descriptions.

package/examples/local-markdown/index.md

@@ -0,0 +1,11 @@
+# okfy Local Markdown Fixture
+
+This fixture models a small docs folder that can be imported into OKF without network access.
+
+Start with [Import Local Markdown](guides/import-local-markdown.md), then read [Serve Over MCP](guides/serve-over-mcp.md).
+
+Key topics:
+
+- [OKF bundle structure](concepts/okf-bundle.md)
+- [Progressive disclosure](concepts/progressive-disclosure.md)
+- [MCP tools](reference/mcp-tools.md)

package/examples/local-markdown/okfy-example.json

@@ -0,0 +1,10 @@
+{
+  "sourceCommand": "npx -y okfy-ai import ./examples/local-markdown --out ./tmp/okfy-docs --force --stable-timestamps",
+  "expectedConceptCount": 9,
+  "expectedValidationStatus": "valid",
+  "suggestedAgentQuestions": [
+    "Search for import workflow concepts, read the best match, and explain how to convert a local Markdown folder into OKF.",
+    "Find concepts tagged mcp, read the MCP tools concept, and describe the expected tool-call sequence.",
+    "Read the bundle summary, then identify which concepts are most useful for a first-time okfy user."
+  ]
+}

package/examples/local-markdown/reference/mcp-tools.md

@@ -0,0 +1,25 @@
+# MCP Tools
+
+okfy exposes these read-only MCP tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `search_concepts` | Find concept previews by query, type, or tags. |
+| `read_concept` | Read one concept body, frontmatter, links, backlinks, and source resource. |
+| `get_neighbors` | Traverse outbound links and backlinks around a concept. |
+| `list_types` | Show concept types and counts. |
+| `list_tags` | Show tags and counts. |
+| `bundle_summary` | Show bundle title, concept count, type distribution, connected concepts, and validation status. |
+
+Expected question-answer flow:
+
+```text
+bundle_summary
+search_concepts
+read_concept
+get_neighbors
+read_concept
+answer with citations
+```
+
+Related: [Progressive Disclosure](../concepts/progressive-disclosure.md).

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "okfy-ai",
+  "version": "0.1.2",
+  "description": "Convert docs into Open Knowledge Format bundles and serve them to MCP agents.",
+  "type": "module",
+  "bin": {
+    "okfy": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "assets/logo.svg",
+    "assets/demo.gif",
+    "docs/mcp-clients.md",
+    "examples"
+  ],
+  "keywords": [
+    "okf",
+    "open-knowledge-format",
+    "mcp",
+    "agent-memory",
+    "llm",
+    "docs",
+    "rag",
+    "markdown"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "okfy": "node dist/cli.js",
+    "demo": "node dist/cli.js demo",
+    "publish:npm": "node scripts/publish-npm-readme.mjs",
+    "prepublishOnly": "pnpm build && pnpm test && pnpm typecheck"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.3",
+    "cheerio": "^1.0.0",
+    "commander": "^12.1.0",
+    "gray-matter": "^4.0.3",
+    "minimatch": "^10.0.1",
+    "minisearch": "^7.1.2",
+    "p-limit": "^6.2.0",
+    "picocolors": "^1.1.1",
+    "robots-parser": "^3.0.1",
+    "turndown": "^7.2.0",
+    "zod": "^3.25.64"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@types/node": "^20.19.1",
+    "@types/turndown": "^5.0.5",
+    "eslint": "^9.29.0",
+    "prettier": "^3.5.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0dust/OKFy.git"
+  },
+  "license": "MIT"
+}