okfy-ai 0.1.2 → 0.1.4

package/README.md

@@ -1,27 +1,59 @@
 # okfy-ai
 
-Turn docs into agent-readable Open Knowledge Format bundles.
+Turn docs into agent-readable Open Knowledge Format v0.1-conformant bundles, then serve them to Claude, Codex, Cursor, or any MCP client.
 
-## Install
+## Use With Agents
 
-Run without installing:
+Create a bundle:
 
 ```bash
-npx -y okfy-ai demo
+npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
+npx -y okfy-ai validate ./stripe-checkout-okf
+```
+
+Add it to an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "stripe-okf": {
+      "command": "npx",
+      "args": ["-y", "okfy-ai", "serve", "./stripe-checkout-okf", "--mcp"]
+    }
+  }
+}
+```
+
+Ask your agent:
+
+```text
+Use the stripe-okf MCP server. Search for Checkout Sessions, read the most relevant concepts, inspect neighbors if needed, and explain the minimum backend flow with source URLs.
 ```
 
-Or install globally:
+## Client Setup
+
+Claude Code:
 
 ```bash
-npm install -g okfy-ai
-okfy demo
+claude mcp add --transport stdio stripe-okf -- npx -y okfy-ai serve ./stripe-checkout-okf --mcp
 ```
 
-Requires Node.js 20+.
+Codex:
+
+```toml
+[mcp_servers.stripe_okf]
+command = "npx"
+args = ["-y", "okfy-ai", "serve", "./stripe-checkout-okf", "--mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+enabled = true
+```
+
+Claude Desktop, Cursor, and other `mcpServers` clients can use the JSON config above. More setup: https://github.com/0dust/OKFy/blob/main/docs/mcp-clients.md
 
-## Quick Start
+## Create Bundles
 
-Convert a docs site into an OKF bundle:
+Docs website:
 
 ```bash
 npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
@@ -29,37 +61,58 @@ npx -y okfy-ai validate ./stripe-checkout-okf
 npx -y okfy-ai inspect ./stripe-checkout-okf
 ```
 
-Serve it to an MCP client:
+Local Markdown:
 
 ```bash
-npx -y okfy-ai serve ./stripe-checkout-okf --mcp
+npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" --force
+npx -y okfy-ai validate ./docs-okf
 ```
 
-## Local Markdown
+## Optional CLI Install
+
+You do not need global install for MCP configs. `npx -y okfy-ai ...` is usually better because the MCP client can launch okfy directly.
+
+Install only if you want shorter local commands:
 
 ```bash
-npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" --force
-npx -y okfy-ai validate ./docs-okf
-npx -y okfy-ai serve ./docs-okf --mcp
+npm install -g okfy-ai
+okfy demo
 ```
 
-## MCP Config
+`okfy-ai` is the npm package name. `okfy` is the installed CLI command.
+
+Requires Node.js 20+.
+
+After installing, this MCP config is equivalent:
 
 ```json
 {
   "mcpServers": {
     "docs-okf": {
-      "command": "npx",
-      "args": ["-y", "okfy-ai", "serve", "./docs-okf", "--mcp"]
+      "command": "okfy",
+      "args": ["serve", "./docs-okf", "--mcp"]
     }
   }
 }
 ```
 
-Ask your agent:
+## Demo
 
-```text
-Use the docs-okf MCP server. Search for the relevant topic, read the best matching concepts, inspect neighbors if needed, and answer with source URLs.
+```bash
+npx -y okfy-ai demo
+```
+
+## No-Install MCP Config
+
+```json
+{
+  "mcpServers": {
+    "docs-okf": {
+      "command": "npx",
+      "args": ["-y", "okfy-ai", "serve", "./docs-okf", "--mcp"]
+    }
+  }
+}
 ```
 
 ## CLI Commands
@@ -93,14 +146,18 @@ docs site or Markdown folder
   -> source-backed agent answers
 ```
 
-Each source page or Markdown file becomes one OKF concept in v0.1. Generated bundles are plain files, so they can be opened, reviewed, diffed, committed, and served locally.
+Each non-reserved source page or Markdown file becomes one OKF concept in v0.1. `index.md` and `log.md` are reserved files, not concepts, and generated indexes are plain Markdown. Concept counts, search, graph links, types, tags, and `read_concept` exclude reserved files.
+
+Validation errors are limited to OKF conformance: malformed or missing concept frontmatter, missing `type`, or invalid reserved-file structure. Broken internal links and missing indexes are warnings.
 
 ## Security Defaults
 
 - Crawls respect `robots.txt` by default.
 - Crawls stay same-origin by default.
 - Page count, depth, response size, and concurrency are capped.
-- Private network targets are rejected by default for URL crawls.
+- Private network URL literals and redirects to private targets are rejected by default for URL crawls.
+- Preflight DNS-resolved private targets are rejected before fetch; fetch-time DNS is not IP-pinned.
+- `--force` refuses unsafe output directories such as `.`, `/`, the home dir, repo root, input path, input parent, and symlink output dirs unless an explicit dangerous override is provided.
 - HTML and Markdown are treated as text. Scripts are not executed.
 - MCP tools are read-only in v0.1.