docs: four published READMEs stop documenting symbols that do not exist (#9544)

.changeset/published-readme-symbol-claims-9544.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/driver-sql": patch
+"@objectstack/mcp": patch
+"@objectstack/objectql": patch
+"@objectstack/spec": patch
+---
+
+docs: four published READMEs stop documenting symbols and call sites that do not exist (#9544)
+
+All four packages ship `README.md` in their `files` array with `private` unset, so these
+are the pages npm renders. Each finding was re-measured against the **built `.d.ts`**, not
+against source, because that is what a consumer resolves through the `exports` map.
+
+- **`@objectstack/driver-sql`** — `import type { IDriver } from '@objectstack/spec'` named
+ a type that exists **nowhere in the repository** (0 hits across every package's `src`
+ and `dist`). The real contract is `IDataDriver` on `@objectstack/spec/contracts` — the
+ one `SqlDriver` actually declares (`export class SqlDriver implements IDataDriver`). The
+ adjacent operation list was corrected too: the method is `create`, not `insert`.
+
+- **`@objectstack/mcp`** — `DriverSql` has never existed (the export is `SqlDriver`), and
+ the README then called `DriverSql.configure({...})` on it. Renaming alone would have
+ been wrong twice over: `SqlDriver` has **no static `configure` either**, and `driver:`
+ is not a key of `defineStack` at all. The example now declares a datasource the way the
+ shipped templates do. `MCPServerPlugin.configure({...})` — five call sites — becomes
+ `new MCPServerPlugin({...})`, the form the class's own JSDoc and every in-repo caller
+ use. The documented options block claimed `serverName`, `autoRegisterTools`,
+ `autoExposeObjects`, `enableStreaming`, `port` and `debug`; the real
+ `MCPServerPluginOptions` is `name`, `version`, `transport`, `autoStart`, `instructions`,
+ and the env switches are named instead.
+
+- **`@objectstack/objectql`** — `registerObject` is an **instance** method, so
+ `SchemaRegistry.registerObject(...)` on the class could never run. The example now
+ reaches it through the engine's registry and states the real parameter order
+ (`schema, packageId, namespace?`).
+
+- **`@objectstack/spec`** — the protocol package's own front page imported
+ `MCPServerConfigSchema` from `@objectstack/spec/ai`, which exports `MCPServerRefSchema`.
+ A rename by itself would have swapped a broken import for a broken **parse**: the
+ documented payload was built for a schema that does not exist, and
+ `MCPServerRefSchema.safeParse` rejects it (`transport` is an enum of
+ `stdio | http | websocket`, not an object, and `endpoint` is required and was absent).
+ The example is now a payload that parses green, and the page says plainly that tools,
+ resources and prompts are derived from metadata at runtime rather than authored there.

packages/drivers/driver-sql/README.md

@@ -134,10 +134,10 @@ interface SQLDriverConfig {
 The SQL driver implements the standard ObjectStack driver interface:
 
 ```typescript
-import type { IDriver } from '@objectstack/spec';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 
-// All standard operations are supported:
-// find, findOne, insert, update, delete, count
+// `SqlDriver implements IDataDriver` — all standard operations are supported:
+// find, findOne, create, update, delete, count
 ```
 
 ### Advanced Queries

packages/mcp/README.md

@@ -37,42 +37,45 @@ import { MCPServerPlugin } from '@objectstack/mcp';
 
 const stack = defineStack({
  plugins: [
- MCPServerPlugin.configure({
-serverName: 'objectstack-server',
+new MCPServerPlugin({
+name: 'objectstack-server',
  version: '1.0.0',
- autoRegisterTools: true,
  }),
  ],
 });
 ```
 
 ## Configuration
 
+The constructor takes `MCPServerPluginOptions`:
+
 ```typescript
-interface MCPServerConfig {
- /** Server name (shown to AI clients) */
-serverName?: string;
+interface MCPServerPluginOptions {
+ /** Override MCP server name. Defaults to 'objectstack'. */
+name?: string;
 
- /** Server version */
+ /** Override MCP server version. Defaults to package version. */
  version?: string;
 
- /** Auto-register tools from actions and flows */
- autoRegisterTools?: boolean;
-
- /** Auto-expose objects as resources */
- autoExposeObjects?: boolean;
-
- /** Enable streaming for large responses */
- enableStreaming?: boolean;
-
- /** Transport mechanism ('stdio' | 'http') */
+ /** Transport mode: 'stdio' (default). */
  transport?: 'stdio' | 'http';
 
- /** HTTP port (if transport is 'http') */
- port?: number;
+ /** Whether to auto-start the MCP server. Defaults to false. */
+ autoStart?: boolean;
+
+ /** Custom instructions for the MCP server. */
+ instructions?: string;
 }
 ```
 
+Tools and resources are **not** opted into per-option — the plugin bridges the
+AI tool registry, metadata service and data engine automatically when it
+starts. The HTTP surface needs no start at all: it is served per-request at
+`/api/v1/mcp` (default-on; `OS_MCP_SERVER_ENABLED=false` opts out).
+
+Environment overrides: `OS_MCP_SERVER_NAME`, `OS_MCP_SERVER_TRANSPORT`,
+`OS_MCP_SERVER_ENABLED`.
+
 ## MCP Tools
 
 ### Auto-Generated Tools
@@ -389,43 +392,57 @@ Configure in Cline settings:
 ### Stdio Transport (Default)
 
 ```typescript
-// server.ts
+// objectstack.config.ts
 import { defineStack } from '@objectstack/spec';
+import { defineDatasource } from '@objectstack/spec/data';
 import { MCPServerPlugin } from '@objectstack/mcp';
-import { DriverSql } from '@objectstack/driver-sql';
 
-const stack = defineStack({
- driver: DriverSql.configure({
- client: 'better-sqlite3',
- connection: { filename: process.env.DATABASE_URL ?? './data/app.db' },
- }),
+export default defineStack({
+ manifest: {
+ id: 'com.example.crm',
+ namespace: 'crm',
+ version: '0.1.0',
+ type: 'app',
+ name: 'My CRM',
+ engines: { protocol: '^17' },
+ },
+ // Optional: the CLI already anchors a persistent SQLite database at
+ // `<project>/.objectstack/data/standalone.db`. Declare a datasource only
+ // to point somewhere else.
+ datasources: [
+ defineDatasource({
+ name: 'primary',
+ label: 'Primary',
+ driver: 'sqlite',
+ config: { filename: '.objectstack/data/app.db' },
+ }),
+ ],
  plugins: [
- MCPServerPlugin.configure({
-serverName: 'my-crm',
+new MCPServerPlugin({
+name: 'my-crm',
  transport: 'stdio', // Claude Desktop, Cursor, Cline
+ autoStart: true, // stdio is a long-lived transport, so start it
  }),
  ],
 });
-
-await stack.boot();
 ```
 
+Run it with the CLI (`os dev` / `os serve`) — `defineStack()` returns the
+metadata definition; the CLI boots the kernel from it.
+
 ### HTTP Transport
 
 ```typescript
-const stack = defineStack({
-driver: DriverSql.configure({ /* ... */ }),
+export default defineStack({
+manifest: { /* ... */ },
  plugins: [
- MCPServerPlugin.configure({
-serverName: 'my-crm',
+new MCPServerPlugin({
+name: 'my-crm',
  transport: 'http',
- port: 3100,
  }),
  ],
 });
-
-await stack.boot();
-// MCP server running on http://localhost:3100
+// Served per-request by the running server at /api/v1/mcp
 ```
 
 ## Advanced Features
@@ -549,13 +566,13 @@ The MCP server exposes these capabilities:
 
 ## Debugging
 
-Enable debug logging:
+The plugin logs through the kernel logger — there is no `debug` option. The
+MCP surface is controlled by environment variables:
 
-```typescript
-MCPServerPlugin.configure({
- serverName: 'my-crm',
- debug: true, // Log all MCP messages
-});
+```bash
+OS_MCP_SERVER_ENABLED=true # explicit true also auto-starts the stdio transport
+OS_MCP_SERVER_NAME=my-crm # override the server name
+OS_MCP_SERVER_TRANSPORT=http # override the transport
 ```
 
 View MCP messages in client:
@@ -566,51 +583,34 @@ View MCP messages in client:
 ## Example: Complete CRM Server
 
 ```typescript
-import { defineStack, defineTool } from '@objectstack/spec';
+// objectstack.config.ts
+import { defineStack } from '@objectstack/spec';
 import { MCPServerPlugin } from '@objectstack/mcp';
 
-const stack = defineStack({
- driver: /* ... */,
- plugins: [
- MCPServerPlugin.configure({
- serverName: 'crm-assistant',
- autoRegisterTools: true,
- }),
- ],
-});
-
-await stack.boot();
-
-const mcp = stack.kernel.getService('mcp');
-
-// Register custom tools
-mcp.registerTool(defineTool({
- name: 'forecast_revenue',
- description: 'Forecast revenue based on pipeline',
- async execute() {
- // Implementation
- },
-}));
-
-// Register custom resources
-mcp.registerResource({
- uri: 'objectstack://dashboards/sales',
- name: 'Sales Dashboard',
- async read() {
- // Implementation
- },
-});
-
-// Register prompts
-mcp.registerPrompt({
- name: 'weekly_report',
- description: 'Generate weekly sales report',
- async render() {
- // Implementation
+import * as objects from './src/objects/index.js';
+import { allActions } from './src/actions/index.js';
+
+export default defineStack({
+ manifest: {
+ id: 'com.example.crm',
+ namespace: 'crm',
+ version: '0.1.0',
+ type: 'app',
+ name: 'CRM Assistant',
+ engines: { protocol: '^17' },
  },
+ objects: Object.values(objects),
+ // Your actions become MCP tools — the plugin bridges them at start.
+ actions: allActions,
+ plugins: [new MCPServerPlugin({ name: 'crm-assistant' })],
 });
 ```
 
+There is no imperative "register a tool" call to make: the plugin derives the
+tool set from your metadata. The bridging helpers it uses —
+`registerObjectTools`, `registerActionTools` and `registerSkillPrompts` — are
+exported for hosts that drive an `MCPServerRuntime` directly.
+
 ## License
 
 Apache-2.0. See [LICENSING.md](../../LICENSING.md).

packages/objectql/README.md

@@ -60,10 +60,12 @@ for (const obj of objects) {
 ### Schema Registry
 
 ```typescript
-import { SchemaRegistry, computeFQN } from '@objectstack/objectql';
+import { computeFQN, type SchemaRegistry } from '@objectstack/objectql';
 
-// Register an object under a namespace
-SchemaRegistry.registerObject(taskDef, 'com.acme.todo', 'todo');
+// `registerObject` is an INSTANCE method — reach the engine's registry.
+// Signature: (schema, packageId, namespace?, ownership?, priority?)
+const registry: SchemaRegistry = engine.registry;
+registry.registerObject(taskDef, 'com.acme.todo', 'todo');
 
 // Resolve FQN
 computeFQN('todo', 'task'); // => 'todo__task'