org-knowledge-layer 0.2.0__tar.gz → 0.3.0__tar.gz

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/.claude/settings.local.json

@@ -130,7 +130,32 @@
       "Bash(check)",
       "Bash(okl bootstrap *)",
       "Bash(git -c core.hooksPath=/dev/null commit -qm 'First-run experience: seeding is a choice, briefings are capped, empty states are honest *)",
-      "Bash(git -c core.hooksPath=/dev/null commit -q --amend -F /tmp/msg.txt)"
+      "Bash(git -c core.hooksPath=/dev/null commit -q --amend -F /tmp/msg.txt)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'v0.2.0 *)",
+      "Bash(command -v postgres pg_ctl initdb)",
+      "Read(//opt/homebrew/opt/**)",
+      "Bash(python3 -c \"import mcp; print\\(mcp.__version__ if hasattr\\(mcp,'__version__'\\) else 'installed'\\)\")",
+      "Bash(python3 -m pip install -q \"psycopg[binary]>=3.1\")",
+      "Bash(python3 -m pip install -q \"mcp>=1.2\")",
+      "Bash(python3 -c \"import mcp; print\\('mcp installed'\\)\")",
+      "Bash(python3 -c \"import mcp, importlib.metadata as md; print\\('installed mcp version:', md.version\\('mcp'\\)\\)\")",
+      "Bash(python3 -c \"from mcp.server.mcpserver import MCPServer; print\\('MCPServer exists'\\); import inspect; print\\('has .tool\\(\\):', hasattr\\(MCPServer, 'tool'\\)\\); print\\('has .list_tools\\(\\):', hasattr\\(MCPServer,'list_tools'\\)\\); print\\('has .run\\(\\):', hasattr\\(MCPServer,'run'\\)\\)\")",
+      "Bash(python3 -m pytest -q -k \"mcp_server_builds or postgres_matches\" -v)",
+      "Bash(OKL_TEST_POSTGRES_URL=\"postgresql://joshuadell@/postgres?host=/tmp/oklpg&port=55432\" python3 -m pytest -q -k \"postgres_matches\" -v)",
+      "Bash(python3 -c \"import importlib.metadata as m; print\\(m.version\\('mcp'\\)\\)\")",
+      "Bash(OKL_TEST_POSTGRES_URL=\"postgresql://joshuadell@/postgres?host=/tmp/oklpg&port=55432\" python3 -m pytest -k \"postgres_matches\")",
+      "Bash(export OKL_TEST_POSTGRES_URL=\"postgresql://okl@/okltest?host=/tmp/oklpg&port=55432\")",
+      "Bash(python3 -m pytest -q -k \"postgres_matches\")",
+      "Bash(export OKL_DATABASE_URL=\"postgresql://okl@/okltest?host=/tmp/oklpg&port=55432\")",
+      "Bash(export OKL_TOKEN=\"deploy-test-secret\")",
+      "Bash(python3 -m uvicorn --factory okl.service:create_app --host 127.0.0.1 --port 8791)",
+      "Bash(echo \"started pid $!\")",
+      "Bash(curl -s http://127.0.0.1:8791/health)",
+      "Bash(OKL_TEST_POSTGRES_URL=\"postgresql://okl@/okltest?host=/tmp/oklpg&port=55432\" python3 -m pytest -q)",
+      "Bash(pkill -f uvicorn)",
+      "Bash(pg_ctl -D /tmp/oklpg/data stop -m immediate)",
+      "Bash(tmutil listlocalsnapshots *)",
+      "Bash(python3 -c \"import json,sys; print\\(', '.join\\(sorted\\(json.load\\(sys.stdin\\)['releases']\\)\\)\\)\")"
     ],
     "additionalDirectories": [
       "/Users/joshuadell/Dev/okl/e2e/scratch-briefed/.okl",

org_knowledge_layer-0.3.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.3.0
+
+Everything here came from running three things that had been written but never
+executed: the MCP server, the Postgres backend, and a deployment.
+
+### Security
+
+- **The service token now covers reads.** Previously `OKL_TOKEN` gated writes only, so
+  an unauthenticated `GET /nodes` returned the entire store — every recorded defect,
+  retired identifier and architecture decision. Every route now requires the token when
+  it is set, except `/health`, which is left open for schedulers and returns no record
+  content.
+- **`okl connect --token` no longer commits your secret.** The token is stored in
+  cleartext in `.okl/config.json`, and a comment claimed the directory was gitignored
+  while nothing wrote a `.gitignore`. `okl init` and `okl connect` now write
+  `.okl/.gitignore`.
+- **A rejected check no longer reports success.** A 401 surfaced as `ValueError` rather
+  than `OKLUnreachable`, so an unauthorized `okl check` exited 0 with a traceback — which
+  a pre-task hook reads as "no rules apply". It now fails closed with exit 2, as does
+  every other command, via a backstop in `main()`.
+
+**Breaking:** if you run a service with `OKL_TOKEN` set, clients must upgrade too.
+Clients older than 0.3.0 send no credential on `GET` requests and will get 401s from
+`okl drift` and the recurrence metric. Upgrade the service and its clients together, or
+unset `OKL_TOKEN` during the rollover.
+
+### Fixed
+
+- `uvicorn okl.service:app` served a module-level `None`: the process started, bound the
+  port, passed a port-liveness check and returned 500 to every request. The app is now
+  built lazily in a module `__getattr__`, so the standard ASGI entrypoint works while
+  importing the module still does not touch the database.
+- The MCP server could not start under `mcp` 2.x, which renamed `FastMCP` to
+  `MCPServer` — and the error handler told you to install the extra you had just
+  installed. Both names are tried, and the real import error is reported.
+- Every MCP `okl_record` call with `scope="repo"` failed. The repo default used
+  `setdefault`, which cannot replace an explicit `None`, and the MCP tools pass every
+  field explicitly.
+- MCP validation errors raised as an opaque "Error executing tool". They now return the
+  complaint, so an agent that invents a tag is told the vocabulary.
+
+### Added
+
+- `docs/DEPLOY.md`: the shared-service deployment path, including a throwaway Postgres
+  for trying it locally and what each failure mode looks like. Every command in it was
+  run against a real Postgres and a real service.
+- Tests covering the live MCP server, the ASGI entrypoint, service auth on reads, the
+  fail-closed 401, and the config `.gitignore`.
+- The Postgres/SQLite parity test now runs in a scratch schema it creates and drops. The
+  first version opened with `DELETE FROM node` against whatever `OKL_TEST_POSTGRES_URL`
+  pointed at, which would have destroyed the store of anyone who set it to their real
+  service.
+
+## 0.2.0 and earlier
+
+See the git history.

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: org-knowledge-layer
-Version: 0.2.0
+Version: 0.3.0
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -566,17 +566,19 @@ okl serve --port 8080
 
 ```bash
 pip install "org-knowledge-layer[service]"
-OKL_DATABASE_URL="sqlite:///okl.db" OKL_TOKEN="a-shared-secret" okl serve
+OKL_DATABASE_URL="postgresql://user:pass@host/okl" OKL_TOKEN="a-shared-secret" okl serve
 # repos then: okl connect https://your-host --token a-shared-secret
 ```
 
-`OKL_TOKEN` (optional) gates **writes**; **reads stay open** — `/nodes` returns the
-whole store to anyone who can reach the port. A mature store holds your defect history,
-security patterns and internal architecture, so treat it as sensitive: bind it to a
-private network or put authentication in front of every route before exposing it. See
-[SECURITY.md](SECURITY.md). Deploy the service
-wherever you like — it's storage-agnostic by design (a `Dockerfile` and a
-`fly.toml` are the obvious next commit; not included in v0).
+**Set `OKL_TOKEN`.** With it, every route requires the bearer token except `/health`
+(left open so schedulers can probe it). Without it, every route is open — including
+`GET /nodes`, which hands the whole store to anyone who can reach the port. A mature
+store is a catalogue of your known defects and internal architecture, which is a map of
+where you are weak. It is a single shared secret with no per-repo scoping or rotation;
+put a real authenticating proxy in front if you need more.
+
+Full instructions, including a throwaway Postgres for trying it locally and what the
+failure modes look like: **[docs/DEPLOY.md](docs/DEPLOY.md)**.
 
 ## Agent integration (MCP)
 

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/README.md

@@ -534,17 +534,19 @@ okl serve --port 8080
 
 ```bash
 pip install "org-knowledge-layer[service]"
-OKL_DATABASE_URL="sqlite:///okl.db" OKL_TOKEN="a-shared-secret" okl serve
+OKL_DATABASE_URL="postgresql://user:pass@host/okl" OKL_TOKEN="a-shared-secret" okl serve
 # repos then: okl connect https://your-host --token a-shared-secret
 ```
 
-`OKL_TOKEN` (optional) gates **writes**; **reads stay open** — `/nodes` returns the
-whole store to anyone who can reach the port. A mature store holds your defect history,
-security patterns and internal architecture, so treat it as sensitive: bind it to a
-private network or put authentication in front of every route before exposing it. See
-[SECURITY.md](SECURITY.md). Deploy the service
-wherever you like — it's storage-agnostic by design (a `Dockerfile` and a
-`fly.toml` are the obvious next commit; not included in v0).
+**Set `OKL_TOKEN`.** With it, every route requires the bearer token except `/health`
+(left open so schedulers can probe it). Without it, every route is open — including
+`GET /nodes`, which hands the whole store to anyone who can reach the port. A mature
+store is a catalogue of your known defects and internal architecture, which is a map of
+where you are weak. It is a single shared secret with no per-repo scoping or rotation;
+put a real authenticating proxy in front if you need more.
+
+Full instructions, including a throwaway Postgres for trying it locally and what the
+failure modes look like: **[docs/DEPLOY.md](docs/DEPLOY.md)**.
 
 ## Agent integration (MCP)
 

org_knowledge_layer-0.3.0/docs/DEPLOY.md

@@ -0,0 +1,171 @@
+# Deploying the shared service
+
+okl runs in two modes. **Local mode** keeps a SQLite file next to your config and needs
+no deployment; it is the right choice for one person on one machine, and everything in
+the README works there. **Shared mode** puts one service in front of one database so
+that every repo, on every machine, reads and writes the same curated knowledge. This
+document covers the second.
+
+The reason to bother: a lesson recorded in one repo is worth something only if a
+different repo, weeks later, is told about it before it makes the same mistake. That
+cross-repo hop is the whole point of the layer, and it needs a shared store.
+
+Every command below was run against a real Postgres and a real service while writing
+this page. Where something is **not** verified, it says so.
+
+---
+
+## 1. A database
+
+Postgres is the supported shared backend. The service selects it with one environment
+variable and nothing else in the code changes:
+
+```bash
+export OKL_DATABASE_URL="postgresql://user:pass@host:5432/okl"
+```
+
+Any managed Postgres works — RDS, Cloud SQL, Neon, Supabase, Fly Postgres. The schema
+is created on first connect; there is no migration step to run.
+
+To try it locally first, a throwaway cluster in four commands:
+
+```bash
+initdb -D /tmp/oklpg/data -U okl --auth=trust
+pg_ctl -D /tmp/oklpg/data -o "-p 55432 -k /tmp/oklpg -c listen_addresses=''" start
+createdb -h /tmp/oklpg -p 55432 -U okl okltest
+export OKL_TEST_POSTGRES_URL="postgresql://okl@/okltest?host=/tmp/oklpg&port=55432"
+```
+
+That last variable also switches on the backend-parity test, which loads one corpus into
+both SQLite and Postgres and asserts they rank the same record first for the same query:
+
+```bash
+pytest -k postgres_matches
+```
+
+Run it when you change anything about retrieval. SQLite ranks with BM25 and Postgres with
+`ts_rank`; they have diverged before, and the failure mode is quiet — a repo that moves to
+the shared service silently gets worse retrieval than it had on a laptop. The test builds
+its tables in a temporary schema and drops them afterwards, so it is safe to point at a
+database that already has data, though pointing it at production is still a strange thing
+to do.
+
+## 2. A token
+
+**Set `OKL_TOKEN`.** It is optional in the code and mandatory in practice:
+
+```bash
+export OKL_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
+```
+
+With it set, every endpoint requires `Authorization: Bearer <token>` except `/health`.
+Without it, every endpoint is open to anyone who can reach the port — including
+`GET /nodes`, which returns the entire store in one request. A mature okl store is a
+catalogue of your organization's known defects, its retired identifiers and its internal
+architecture decisions. That is a map of where you are weak, and it is precisely the
+material the layer exists to accumulate.
+
+`/health` stays open deliberately: schedulers and load balancers probe it before they
+hold any credential, and a service that cannot be health-checked never goes live. It
+returns a record count and a backend name, never record content.
+
+The token is a single shared secret with no per-repo scoping, rotation or audit trail.
+That is honest for what this is. If you need more, put a real authenticating proxy in
+front and leave `OKL_TOKEN` set underneath as defence in depth.
+
+## 3. Run it
+
+```bash
+pip install "org-knowledge-layer[service]"
+okl serve --port 8080                       # convenience wrapper
+uvicorn okl.service:app --host 0.0.0.0 --port 8080   # standard ASGI entrypoint
+```
+
+Both work and serve the same app. Use the second one under a process manager or in a
+container, since it is the form every platform's default start command takes.
+
+Confirm it is up:
+
+```bash
+curl -s localhost:8080/health
+# {"ok":true,"nodes":5,"backend":"postgresql"}
+```
+
+`backend` in that response is worth reading on every deploy. If it says `sqlite` when you
+expected `postgresql`, `OKL_DATABASE_URL` did not reach the process, and the service is
+happily serving an empty file-backed store that will vanish with the container.
+
+## 4. Point repos at it
+
+In each repo:
+
+```bash
+okl init --repo checkout-api
+okl connect https://okl.internal --token "$OKL_TOKEN"
+```
+
+`connect` writes the URL and token to `.okl/config.json`, and okl drops a `.gitignore`
+inside `.okl/` so that file is never committed. Prefer supplying the token through the
+`OKL_TOKEN` environment variable in CI and shared machines; the config file is a
+convenience for a developer laptop.
+
+That is the whole client setup. From then on:
+
+```bash
+# in checkout-api
+okl record --type Defect --scope org \
+  --title "Refund amount trusted from the client body" \
+  --symptom "a refund endpoint reads amount from the request" \
+  --fix "look the original charge up server-side and refund that"
+
+# later, in billing-worker — a different repo, a different machine
+okl check --task "add an endpoint that issues a refund" --format actions
+# OKL — 1 rule(s) apply before you start:
+# - FIX: Refund amount trusted from the client body [when: a refund endpoint reads amount from the request]
+#   -> look the original charge up server-side and refund that
+```
+
+Note the scope. `--scope org` is what makes a lesson cross repo boundaries; `--scope repo`
+keeps it local to the repo that recorded it. Getting this wrong is the most common way a
+shared store disappoints: everything is recorded, nothing propagates.
+
+## 5. What failure looks like
+
+The service being unreachable, or refusing your token, must never be reported as "no
+rules apply". Silence and safety are indistinguishable to an agent, and only one of them
+is safe. Both cases exit non-zero and say which is which:
+
+```
+$ okl check --task "issue a refund"          # no token
+OKL REFUSED THE CHECK — refusing to report a clean check.
+OKL service rejected the request (401): missing or bad bearer token
+
+$ okl check --task "issue a refund"          # service down
+OKL UNREACHABLE — refusing to report a clean check.
+OKL service unreachable at http://okl.internal/check: ...
+```
+
+The pre-task hook and the CI verifier both treat a non-zero exit as a block. If you wrap
+okl in your own tooling, do the same: a check that cannot run has not passed.
+
+## Containers
+
+**Not verified.** No Docker daemon was available where this was written, so the project
+ships no Dockerfile rather than an untested one. The service is an ordinary ASGI app with
+no filesystem state when `OKL_DATABASE_URL` points at Postgres, so a container is four
+lines over `python:3.12-slim`: install `org-knowledge-layer[service]`, expose the port,
+and run the `uvicorn okl.service:app` command above. Set `OKL_DATABASE_URL` and
+`OKL_TOKEN` as secrets, and point the platform's health check at `/health`.
+
+If you build one, a PR adding it — with the build running in CI, so the claim is backed
+by something — is welcome.
+
+## Cost of the shared mode
+
+Worth stating plainly before you commit to it. One service and one database is one more
+thing to run, monitor and back up, and okl gives you no operational tooling for any of
+that. It has no migrations, no backup command, no per-repo access control and no audit
+log. Local mode has none of those problems.
+
+Move to shared mode when a second repo actually needs a first repo's lessons. Before
+that, the file on your laptop is doing the same job with none of the operations.

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # Distribution name only. The CLI command, the import package, and the repo are all `okl`;
 # PyPI rejects `okl` as too similar to the existing `oki` (l/i are treated as confusable).
 name = "org-knowledge-layer"
-version = "0.2.0"
+version = "0.3.0"
 description = "Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos."
 readme = "README.md"
 requires-python = ">=3.10"

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/src/okl/cli.py

@@ -184,6 +184,13 @@ def cmd_check(args) -> int:
         # FAIL CLOSED — loud, non-zero, no reassuring empty result.
         print(f"OKL UNREACHABLE — refusing to report a clean check.\n{e}", file=sys.stderr)
         return 2
+    except ValueError as e:
+        # A 4xx (usually a 401 against a token-protected service) is a REFUSED check,
+        # not a clean one, so it fails closed just the same. It gets its own message
+        # because the fix is different: a credential, not connectivity. Before this,
+        # an unauthorized check exited 0 with a raw urllib traceback.
+        print(f"OKL REFUSED THE CHECK — refusing to report a clean check.\n{e}", file=sys.stderr)
+        return 2
     if args.format == "json":
         _print_json(result)
     elif args.format == "actions":
@@ -203,7 +210,16 @@ def cmd_record(args) -> int:
                   id=args.id)
     if args.repo:
         kwargs["repo"] = args.repo
-    node_id = client.record(**{k: v for k, v in kwargs.items() if v is not None})
+    try:
+        node_id = client.record(**{k: v for k, v in kwargs.items() if v is not None})
+    except ValueError as e:
+        # An unknown tag or a malformed scope is the caller's mistake, and the exception
+        # text names the vocabulary they need. A traceback buries that under a stack.
+        print(f"NOT RECORDED — {e}", file=sys.stderr)
+        return 2
+    except OKLUnreachable as e:
+        print(f"NOT RECORDED — {e}", file=sys.stderr)
+        return 2
     print(node_id)
     return 0
 
@@ -589,7 +605,15 @@ def build_parser() -> argparse.ArgumentParser:
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
-    return args.func(args)
+    try:
+        return args.func(args)
+    except (ValueError, OKLUnreachable) as e:
+        # The backstop, so no command can ever answer a rejected or unreachable service
+        # with a Python traceback. Commands that can say something more specific catch
+        # these themselves and never reach here; this exists so the ones that do not —
+        # and the ones added later — still exit non-zero with a line a human can act on.
+        print(f"OKL: {e}", file=sys.stderr)
+        return 2
 
 
 if __name__ == "__main__":

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/src/okl/client.py

@@ -40,6 +40,15 @@ def load_config() -> dict[str, Any]:
 def save_config(data: dict[str, Any], root: Path | None = None) -> Path:
     d = (root or Path.cwd()) / CONFIG_DIR
     d.mkdir(parents=True, exist_ok=True)
+    # Ignore the whole directory, from inside it. Everything okl writes here is either
+    # machine-local (`okl_bin`, an absolute interpreter path) or secret (`token`, the
+    # service bearer credential that `okl connect --token` stores in cleartext), and the
+    # local store lands here too. The code claimed ".okl/ is gitignored" while writing
+    # nothing to make that true, so a `git add .` after `okl connect --token` committed
+    # a shared secret. A .gitignore inside .okl/ needs no edit to the repo's own.
+    gitignore = d / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("# okl: machine-local config, credentials and local store\n*\n")
     path = d / CONFIG_FILE
     path.write_text(json.dumps(data, indent=2) + "\n")
     return path
@@ -115,7 +124,11 @@ class Client:
     def record(self, **kwargs) -> str:
         # Default the repo in BOTH modes: `--scope repo` needs it to become repo:<name>,
         # and the remote path used to skip this (found by E2E: 400 on every repo-scoped record).
-        kwargs.setdefault("repo", self.repo)
+        # `setdefault` is not enough: callers that pass every field explicitly (the MCP
+        # tools do) send repo=None, so the key EXISTS and setdefault leaves the None in
+        # place. Found by live-testing the MCP server: every scope="repo" record failed.
+        if kwargs.get("repo") is None:
+            kwargs["repo"] = self.repo
         if self.mode == "remote":
             return self._post("/record", kwargs)["id"]
         return core.record(self._local_store(), **kwargs)
@@ -157,10 +170,24 @@ class Client:
         return self._local_store().all_nodes()
 
     def _get(self, path: str) -> dict:
+        # The token goes on GETs too. It used to go only on POSTs, which was survivable
+        # only because the service left reads open; once reads are gated, an unauthenticated
+        # GET makes drift detection (/nodes) and the recurrence metric fail against every
+        # private deployment — and a 401 here surfaces as "unreachable", i.e. as an outage.
         url = self.service_url.rstrip("/") + path
+        req = _req.Request(url)
+        token = os.environ.get("OKL_TOKEN") or self.config.get("token")
+        if token:
+            req.add_header("Authorization", f"Bearer {token}")
         try:
-            with _req.urlopen(url, timeout=10) as resp:
+            with _req.urlopen(req, timeout=10) as resp:
                 return json.loads(resp.read())
+        except HTTPError as e:
+            if 400 <= e.code < 500:
+                raise ValueError(
+                    f"OKL service rejected the request ({e.code} {e.reason}). "
+                    "If this is 401, set OKL_TOKEN or add \"token\" to .okl/config.json.") from e
+            raise OKLUnreachable(f"OKL service error at {url}: {e.code} {e.reason}") from e
         except URLError as e:
             raise OKLUnreachable(f"OKL service unreachable at {url}: {e}") from e
 

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/src/okl/mcp_server.py

@@ -13,12 +13,33 @@ from .client import Client, OKLUnreachable
 
 
 def _build():
-    try:
-        from mcp.server.fastmcp import FastMCP
-    except ImportError as e:  # pragma: no cover
-        raise RuntimeError("The MCP server needs the 'mcp' package — install okl[mcp]") from e
+    """Construct the MCP server, tolerating both major versions of the SDK.
 
-    mcp = FastMCP("okl")
+    The class was renamed in mcp 2.x: `mcp.server.fastmcp.FastMCP` became
+    `mcp.server.mcpserver.MCPServer`. The decorator API we use (`.tool()`) is the same
+    on both, so try the newer name first and fall back. Without this, `pip install
+    org-knowledge-layer[mcp]` resolves to 2.x and every tool call fails.
+    """
+    server_cls = None
+    errors = []
+    for module, name in (("mcp.server.mcpserver", "MCPServer"),   # mcp >= 2
+                         ("mcp.server.fastmcp", "FastMCP")):      # mcp 1.x
+        try:
+            server_cls = getattr(__import__(module, fromlist=[name]), name)
+            break
+        except (ImportError, AttributeError) as e:
+            errors.append(f"{module}.{name}: {e}")
+    if server_cls is None:
+        # Surface the REAL cause. Saying "install okl[mcp]" to someone who just did is
+        # the same failure as reporting a validation error as an outage: the message
+        # sends them to fix a thing that is not broken.
+        raise RuntimeError(
+            "Could not load an MCP server class from the installed 'mcp' package.\n"
+            + "\n".join(f"  tried {e}" for e in errors)
+            + "\nInstall the extra with `pip install \"org-knowledge-layer[mcp]\"`, or report "
+              "this if the SDK has changed again.")
+
+    mcp = server_cls("okl")
     client = Client()
 
     @mcp.tool()
@@ -62,9 +83,15 @@ def _build():
         tags (comma-sep, controlled vocabulary — e.g. react, security,
         eval-integrity) categorize the subject so `check` can filter by interest.
         """
-        node_id = client.record(type=type, title=title, scope=scope, body=body,
-                                 status=status, found_by=found_by, ttl_days=ttl_days, repo=repo,
-                                 symptom=symptom, fix=fix, files=files, tags=tags)
+        try:
+            node_id = client.record(type=type, title=title, scope=scope, body=body,
+                                    status=status, found_by=found_by, ttl_days=ttl_days,
+                                    repo=repo, symptom=symptom, fix=fix, files=files, tags=tags)
+        except ValueError as e:
+            # Hand the agent the actual complaint (unknown tag, bad scope) so it can fix
+            # its own call. Raising here surfaces as an opaque "Error executing tool",
+            # which reads like an outage and teaches the agent nothing.
+            return f"NOT RECORDED — {e}"
         return f"recorded {node_id} ({type}, {scope})"
 
     @mcp.tool()

{org_knowledge_layer-0.2.0 → org_knowledge_layer-0.3.0}/src/okl/service.py

@@ -68,19 +68,28 @@ class VerifyReq(BaseModel):
 def create_app(store: Store | None = None) -> FastAPI:
     app = FastAPI(title="OKL — the sixth surface", version="0.1.0")
     _store = store or Store(os.environ.get("OKL_DATABASE_URL"))
-    # Optional shared-secret gate. If OKL_TOKEN is set, writes require it.
-    write_token = os.environ.get("OKL_TOKEN")
+    # Optional shared-secret gate. If OKL_TOKEN is set it covers READS as well as
+    # writes. Reads used to be open while writes were gated, which meant a deployed
+    # service handed anyone who found the URL a `GET /nodes` dump of the org's entire
+    # encoded body — its known defects, its retired identifiers, its architecture
+    # decisions. That is a catalogue of where the org is weak, and it is exactly the
+    # material the layer exists to collect. If you set a token, you want it private.
+    token = os.environ.get("OKL_TOKEN")
 
     def _auth(authorization: str | None) -> None:
-        if write_token and authorization != f"Bearer {write_token}":
+        if token and authorization != f"Bearer {token}":
             raise HTTPException(status_code=401, detail="missing or bad bearer token")
 
     @app.get("/health")
     def health() -> dict[str, Any]:
+        # Deliberately open even when a token is set: schedulers and load balancers
+        # probe this before they hold any credential, and a deploy that cannot be
+        # health-checked never goes live. It returns a count and a backend name, no content.
         return {"ok": True, "nodes": len(_store.all_nodes()), "backend": _store.url.split(":")[0]}
 
     @app.post("/check")
-    def check(req: CheckReq) -> dict[str, Any]:
+    def check(req: CheckReq, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+        _auth(authorization)
         return core.check(_store, req.repo, req.task, limit=req.limit,
                           interests=req.interests)
 
@@ -96,7 +105,8 @@ def create_app(store: Store | None = None) -> FastAPI:
         return {"id": node_id}
 
     @app.post("/search")
-    def search(req: SearchReq) -> dict[str, Any]:
+    def search(req: SearchReq, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+        _auth(authorization)
         return {"results": core.search(_store, req.query, req.scope, req.node_types, req.limit)}
 
     @app.post("/link")
@@ -114,12 +124,14 @@ def create_app(store: Store | None = None) -> FastAPI:
             raise HTTPException(status_code=400, detail=str(e)) from e
 
     @app.get("/metric/recurrence")
-    def recurrence() -> dict[str, Any]:
+    def recurrence(authorization: str | None = Header(default=None)) -> dict[str, Any]:
+        _auth(authorization)
         rows = _store.recurrence_after_arming()
         return {"recurrence_after_arming": rows, "count": len(rows)}
 
     @app.get("/nodes")
-    def nodes() -> dict[str, Any]:
+    def nodes(authorization: str | None = Header(default=None)) -> dict[str, Any]:
+        _auth(authorization)
         from dataclasses import asdict
         rows = [asdict(n) for n in _store.all_nodes()]
         return {"nodes": rows, "count": len(rows)}
@@ -127,11 +139,32 @@ def create_app(store: Store | None = None) -> FastAPI:
     return app
 
 
-app = None
+_app: FastAPI | None = None
+
+
+def __getattr__(name: str):
+    """Build `app` on first attribute access, not at import.
+
+    Every ASGI host — uvicorn, gunicorn, a platform's default start command — is
+    pointed at `module:app`, and that is what this module's own docstring tells you
+    to run. `app` used to be a module-level `None` that `run()` reassigned as a side
+    effect, so `uvicorn okl.service:app` served a None: the process started, bound the
+    port, looked healthy to anything watching the port, and answered 500 to every
+    request. A deploy that fails at startup is a nuisance; one that comes up and then
+    fails every call is an outage that reads as a bug in the caller.
+
+    PEP 562 module `__getattr__` fires only when normal lookup fails, which is what
+    keeps the database out of import time: `import okl.service` still touches nothing,
+    so the CLI and the tests can import this module without a configured backend.
+    """
+    if name == "app":
+        global _app
+        if _app is None:
+            _app = create_app()
+        return _app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 def run(host: str = "0.0.0.0", port: int = 8080) -> None:
     import uvicorn
-    global app
-    app = create_app()
-    uvicorn.run(app, host=host, port=port)
+    uvicorn.run(create_app(), host=host, port=port)