Bump to 0.4.2: fix biome check (import sorting, delete operator, line length)

Author: mgoldsborough

UPJACK_ISSUE_TOOL_VISIBILITY.md

@@ -0,0 +1,103 @@
+# Feature: Tool visibility whitelist in manifest
+
+## Problem
+
+`create_server()` registers every auto-generated tool for every entity — CRUD (6), graph traversal (3), and activity tools per entity type. For an app with 6 entities, that's 67+ tools before any custom tools are added.
+
+This overwhelms LLM clients:
+- Claude Desktop took 16 seconds to process the `tools/list` response (278K chars of tool schemas)
+- LLMs struggle with tool selection when presented with 77 options
+- Most auto-generated tools are irrelevant for the use case (e.g., `create_session` and `delete_speaker` on a read-only conference app)
+
+## Current workaround
+
+Monkey-patching `_list_tools` after `create_server()`:
+
+```python
+mcp = create_server(str(MANIFEST), root=str(WORKSPACE))
+
+_VISIBLE_TOOLS = {"find_sessions", "create_bookmark", "get_speaker", ...}
+
+_original_list_tools = mcp._list_tools
+
+async def _filtered_list_tools():
+    all_tools = await _original_list_tools()
+    return [t for t in all_tools if t.name in _VISIBLE_TOOLS]
+
+mcp._list_tools = _filtered_list_tools
+```
+
+This works — hidden tools remain registered and callable via `tools/call`, they just don't appear in `tools/list`. But it's fragile and requires knowing FastMCP internals.
+
+## Proposed solution
+
+### Option A: Manifest-level visibility per entity
+
+```json
+{
+  "entities": [
+    {
+      "name": "session",
+      "prefix": "ss",
+      "schema": "schemas/session.schema.json",
+      "tools": {
+        "visible": ["get", "search"]
+      }
+    },
+    {
+      "name": "bookmark",
+      "prefix": "bk",
+      "schema": "schemas/bookmark.schema.json",
+      "tools": {
+        "visible": ["create", "list", "delete"]
+      }
+    }
+  ]
+}
+```
+
+`tools.visible` is a whitelist of which auto-generated tool categories to include in `tools/list`. Options: `create`, `get`, `update`, `list`, `search`, `delete`, `query_by_relationship`, `get_related`, `get_composite`.
+
+Default (no `tools` key): all tools visible (current behavior).
+
+### Option B: `create_server()` parameter
+
+```python
+mcp = create_server(
+    manifest_path,
+    root="./workspace",
+    visible_tools=["create_bookmark", "list_bookmarks", "get_session", ...]
+)
+```
+
+### Option C: Global visibility config in manifest
+
+```json
+{
+  "_meta": {
+    "ai.nimblebrain/upjack": {
+      "tool_visibility": {
+        "mode": "whitelist",
+        "include": ["create_bookmark", "list_bookmarks", "delete_bookmark", ...]
+      }
+    }
+  }
+}
+```
+
+## Recommendation
+
+Option A is the best — it's declarative, per-entity, and lives in the manifest where the entity definitions already are. The app author decides at schema time which operations are relevant for each entity type.
+
+For reference data entities (session, speaker, sponsor), you'd set `"visible": ["get"]` or `"visible": ["get", "search"]`. For personal data entities (bookmark, note, connection), you'd set `"visible": ["create", "list", "delete"]` or similar.
+
+## Impact
+
+The MCP Dev Summit app went from 77 tools to 21 visible tools with the workaround. The `tools/list` response dropped from 278K chars to ~50K, and tool selection accuracy improved significantly.
+
+## Notes
+
+- Hidden tools must remain callable — `tools/call` with a hidden tool name should still work
+- This is a listing/discoverability concern, not a security concern
+- Graph traversal and activity tools should also be controllable (default: hidden unless opted in)
+- The `seed_data`, `add_field`, and `rebuild_index` utility tools should have their own visibility toggle

lib/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "upjack"
-version = "0.4.1"
+version = "0.4.2"
 description = "Schema-driven entity management for AI-native applications"
 readme = "README.md"
 license = {text = "Apache-2.0"}

lib/python/src/upjack/__init__.py

@@ -1,6 +1,6 @@
 """NimbleBrain Upjack — schema-driven entity management for AI-native applications."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 from upjack.activity import ACTIVITY_ENTITY_DEF, get_activity_schema
 from upjack.app import UpjackApp

lib/python/uv.lock

@@ -1,6 +1,6 @@
 {
   "name": "upjack",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Schema-driven entity management for AI-native applications",
   "type": "module",
   "exports": {

lib/typescript/package.json

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-// eslint-disable-next-line @typescript-eslint/no-require-imports -- AJV CJS interop
-import Ajv2020Module from "ajv/dist/2020.js";
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- ajv-formats CJS interop
 import addFormatsModule from "ajv-formats";
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- AJV CJS interop
+import Ajv2020Module from "ajv/dist/2020.js";
 
 // CJS default export interop
 const Ajv2020 =

lib/typescript/src/schema.ts

@@ -329,7 +329,9 @@ export function createServer(manifestPath: string, root?: string): Server {
     const { definitions, handlers } = buildEntityTools(app, entityDef, schema);
     Object.assign(allHandlers, handlers);
 
-    const toolsFilter = (entityDef as unknown as Record<string, unknown>).tools as string[] | undefined;
+    const toolsFilter = (entityDef as unknown as Record<string, unknown>).tools as
+      | string[]
+      | undefined;
     if (toolsFilter) {
       const listed = resolveListedTools(entityDef.name, entityDef.plural, toolsFilter);
       listedDefinitions.push(...definitions.filter((d) => listed.has(d.name)));

lib/typescript/src/server.ts

@@ -1,10 +1,10 @@
-import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeEach, describe, expect, it } from "vitest";
 import { UpjackApp } from "../src/app.js";
 import { validateId } from "../src/ids.js";
-import { existsSync } from "node:fs";
 
 const NAMESPACE = "apps/crm";
 const ENTITIES = [

lib/typescript/tests/app.test.ts

@@ -1,7 +1,7 @@
 import { mkdirSync } from "node:fs";
-import { resolve } from "node:path";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { resolve } from "node:path";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { entityDir, entityPath, resolveRoot, schemaDir } from "../src/paths.js";
@@ -75,6 +75,7 @@ describe("resolveRoot", () => {
     if (originalEnv !== undefined) {
       process.env.UPJACK_ROOT = originalEnv;
     } else {
+      // biome-ignore lint/performance/noDelete: env var cleanup requires delete
       delete process.env.UPJACK_ROOT;
     }
   });
@@ -85,11 +86,13 @@ describe("resolveRoot", () => {
   });
 
   it("uses cliRoot when no env var", () => {
+    // biome-ignore lint/performance/noDelete: env var cleanup requires delete
     delete process.env.UPJACK_ROOT;
     expect(resolveRoot("/explicit")).toBe(resolve("/explicit"));
   });
 
   it("falls back to .upjack", () => {
+    // biome-ignore lint/performance/noDelete: env var cleanup requires delete
     delete process.env.UPJACK_ROOT;
     expect(resolveRoot()).toBe(resolve(".upjack"));
   });

lib/typescript/tests/paths.test.ts

@@ -2,7 +2,7 @@
 name: upjack-app-builder
 description: Builds complete, compliant NimbleBrain Upjack apps from natural language descriptions. Generates manifest, entity schemas, skills, context, seed data, and server entry point. Use when creating a new Upjack app, building an AI-native app, or scaffolding a domain-specific application. Triggers include "create me a todo app", "build an upjack app", "new upjack app for", "scaffold an app".
 metadata:
-  version: "0.4.1"
+  version: "0.4.2"
   category: development
   tags:
     - upjack