{"openapi":"3.1.0","info":{"title":"Blueprint Nexus (blueSC) — Public Agent API","summary":"Knowledge graph, ingestion, and MCP tool surface for external agents.","description":"Blueprint Nexus (blueSC) is a living intelligence workspace. This document describes every public, agent-facing HTTP endpoint: the Model Context Protocol (MCP) streamable transport, per-tool execution, REST ingestion, and connection provisioning.\n\n`GET /api/mcp/openapi?workspace_id=…` returns the same surface with one expanded path entry per MCP tool, which is what ChatGPT Custom GPT Actions import.\n\n**Errors are always JSON, never HTML.** Each response documents the envelope it uses: MCP tool execution returns the JSON-RPC 2.0 `error` object (`JsonRpcError`), the REST endpoints return `{ error: string }` (`SimpleError`), and the canonical structured envelope is `ApiError` — `{ error: { code, message, hint, docs } }` — which unmatched routes and new endpoints use.\n\n**Throttling convention.** Every endpoint that enforces a limit publishes the standard `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy` headers on *all* of its responses, and a `429` additionally carries `Retry-After` in seconds. The MCP tool surface enforces 60 requests per 60-second window per workspace API key (`RateLimit-Policy: 60;w=60`) and 60 per window per source IP address, so read `RateLimit-Remaining` and slow down *before* it reaches 0 rather than retrying after a refusal. Limits are per key, not per connection: opening several connections does not multiply the budget.","version":"1.0.0","contact":{"name":"Blueprint Nexus","url":"https://www.bluesc.org","email":"dev@bluesc.org"},"license":{"name":"Proprietary","url":"https://www.bluesc.org/terms"},"x-llms-txt":"/llms.txt","x-mcp-tools":["bkn_list_workspaces","bkn_create_workspace","bkn_query_graph","bkn_ingest_content","bkn_create_node","bkn_link_nodes","bkn_get_workspace_context","bkn_push_telemetry","bkn_mutate_variable","bkn_delete_node","bkn_unlink_nodes","bkn_get_subgraph","agent_traverse_node","bkn_emit_signal","bkn_resolve_signal","bkn_list_signals"]},"servers":[{"url":"https://www.bluesc.org","description":"Production"}],"externalDocs":{"description":"Guides for the workspace, knowledge graph, and agent integrations","url":"https://www.bluesc.org/blog"},"tags":[{"name":"MCP Tools","description":"Model Context Protocol tool execution over JSON-RPC 2.0."},{"name":"Ingestion","description":"Push unstructured text, logs, or documents into the knowledge graph."},{"name":"Connection","description":"Provision and inspect MCP connections and workspace API keys."},{"name":"Discovery","description":"Machine-readable descriptions of this API surface."}],"paths":{"/api/mcp":{"post":{"tags":["MCP Tools"],"summary":"Streamable HTTP MCP transport (JSON-RPC 2.0 over POST)","description":"The recommended transport for new MCP clients: a single stateless endpoint that accepts a JSON-RPC 2.0 request over `POST` and answers with `application/json`. Authenticate with the workspace API key in `Authorization: Bearer bsc_live_…`; no session id is issued and no server state is kept, so a client may POST directly without first opening an SSE stream or calling `initialize`. Prefer this over `GET /api/mcp/sse` (the legacy HTTP+SSE transport). `GET` and `DELETE` are not offered and answer `405`: there is no server-initiated stream to subscribe to and no session to terminate. Rate limited per IP address and per workspace API key; see the throttle headers on every response.","operationId":"streamMcpHttpRequest","security":[{"BearerAuth":[]}],"parameters":[{"name":"Accept","in":"header","required":false,"description":"Send `application/json` (optionally alongside `text/event-stream`). This endpoint always replies with a single JSON body rather than an event stream.","schema":{"type":"string","example":"application/json"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"One JSON-RPC 2.0 `tools/call` request. Select the variant matching the tool you want to call; each variant fixes `params.name` and exposes that tool's argument schema.","anyOf":[{"title":"Call bkn_list_workspaces","type":"object","description":"Invoke **bkn_list_workspaces**: List all available workspaces in Blueprint Nexus with their node counts, descriptions, and modification timestamps.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_list_workspaces","description":"Always \"bkn_list_workspaces\" for this variant."},"arguments":{"type":"object","properties":{"limit":{"type":"number","description":"Maximum number of workspaces to return (default: 10)."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_create_workspace","type":"object","description":"Invoke **bkn_create_workspace**: Create a new project workspace in Blueprint Nexus with automatic registration of ownership, workspace settings, documentation, and initial Knowledge Graph (BKN) nodes.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_create_workspace","description":"Always \"bkn_create_workspace\" for this variant."},"arguments":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the workspace (required)."},"description":{"type":"string","description":"Charter, vision, or architectural summary of the workspace."},"problem_statement":{"type":"string","description":"Core problem or market opportunity addressed by this workspace."},"target_audience":{"type":"string","description":"Target user personas, market segment, or customer profiles."},"technologies":{"type":"array","items":{"type":"string"},"description":"Tech stack, frameworks, or tools used in this workspace."},"scope":{"type":"string","enum":["small","medium","large"],"description":"Estimated scope or scale (default: 'medium')."},"key_features":{"type":"array","items":{"type":"string"},"description":"Key product capabilities or deliverables."},"work_mode":{"type":"string","enum":["solo","team","swarm"],"description":"Workspace collaboration mode (default: 'solo')."},"created_by":{"type":"string","description":"Optional UUID of the user who owns this workspace. Defaults to API key owner or admin."},"initial_nodes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object"}},"required":["name","label"]},"description":"Optional array of initial Knowledge Graph nodes to seed into the workspace BKN."}},"required":["name"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_query_graph","type":"object","description":"Invoke **bkn_query_graph**: Search and retrieve nodes and edges from the workspace Knowledge Graph (BKN). Returns nodes, properties, and typed relationships.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_query_graph","description":"Always \"bkn_query_graph\" for this variant."},"arguments":{"type":"object","properties":{"query":{"type":"string","description":"Optional text query to match node names, descriptions, or properties."},"label":{"type":"string","description":"Optional category filter: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"limit":{"type":"number","description":"Max number of nodes to return (default: 50)."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_ingest_content","type":"object","description":"Invoke **bkn_ingest_content**: Universal Graph Ingestion engine. Analyzes raw unstructured text, application logs, specs, or code snippets, extracts entities and relationships, and automatically upserts them into the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_ingest_content","description":"Always \"bkn_ingest_content\" for this variant."},"arguments":{"type":"object","properties":{"content":{"type":"string","description":"The raw text, markdown document, code, or unstructured string to ingest into the Knowledge Graph."},"source_name":{"type":"string","description":"Name or identifier of the source (e.g., 'mobile-app-logs', 'linear-webhook', 'user-doc.md')."},"source_type":{"type":"string","description":"Category of the source (default: 'mcp_external_app')."}},"required":["content"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_create_node","type":"object","description":"Invoke **bkn_create_node**: Explicitly create or update a single Knowledge Node in the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_create_node","description":"Always \"bkn_create_node\" for this variant."},"arguments":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the node (e.g., 'Auth Token Expiration Exception')."},"label":{"type":"string","description":"Taxonomy label for the node: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"description":{"type":"string","description":"Detailed description or context for this node."},"metadata":{"type":"object","description":"Optional key-value JSON object containing custom properties, external IDs, or telemetry."}},"required":["name","label","description"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_link_nodes","type":"object","description":"Invoke **bkn_link_nodes**: Create a directed, typed edge between two existing nodes in the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_link_nodes","description":"Always \"bkn_link_nodes\" for this variant."},"arguments":{"type":"object","properties":{"source_name":{"type":"string","description":"Name of the source node."},"target_name":{"type":"string","description":"Name of the target node."},"relationship_type":{"type":"string","description":"Type of relationship: 'governs', 'decided_by', 'supports', 'conflicts_with', 'implements', 'supersedes', 'aligns', 'requires', 'blocks', 'triggers', 'references'."},"description":{"type":"string","description":"Rationale or explanation of why these nodes are linked."}},"required":["source_name","target_name","relationship_type"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_get_workspace_context","type":"object","description":"Invoke **bkn_get_workspace_context**: Fetch comprehensive context about the workspace, including executive summary, tech spec, open user stories, tasks, and key Knowledge Graph nodes.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_get_workspace_context","description":"Always \"bkn_get_workspace_context\" for this variant."},"arguments":{"type":"object","properties":{"include_docs":{"type":"boolean","description":"Whether to include full technical spec and executive summary (default: true)."},"include_tasks":{"type":"boolean","description":"Whether to include task epics and milestones (default: true)."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_push_telemetry","type":"object","description":"Invoke **bkn_push_telemetry**: Stream runtime telemetry, errors, or application events from an external app directly into the workspace's activity and audit log.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_push_telemetry","description":"Always \"bkn_push_telemetry\" for this variant."},"arguments":{"type":"object","properties":{"event_name":{"type":"string","description":"Short event identifier (e.g. 'payment_gateway_timeout', 'user_signup_failed')."},"severity":{"type":"string","description":"Severity level: 'info', 'warning', 'error', 'critical'."},"payload":{"type":"object","description":"JSON payload containing diagnostic data, stack trace, or state variables."}},"required":["event_name","payload"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_mutate_variable","type":"object","description":"Invoke **bkn_mutate_variable**: Mutate a Variable Node (e.g. increment daily push-ups counter, toggle smart light switch, or reset state) in the workspace Knowledge Graph. Automatically evaluates and fires connected reactive edge triggers.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_mutate_variable","description":"Always \"bkn_mutate_variable\" for this variant."},"arguments":{"type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the Variable Node to mutate."},"operation":{"type":"string","enum":["increment","decrement","set","toggle","reset"],"description":"Mutation operation to perform."},"amount":{"type":"number","description":"Optional numeric step for increment/decrement (default: 1)."},"value":{"description":"New value when using the 'set' operation."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier","operation"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_delete_node","type":"object","description":"Invoke **bkn_delete_node**: Delete or archive a node in the workspace Knowledge Graph (BKN) and sever all connected relationships.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_delete_node","description":"Always \"bkn_delete_node\" for this variant."},"arguments":{"type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the node to delete."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_unlink_nodes","type":"object","description":"Invoke **bkn_unlink_nodes**: Delete a directed relationship (edge) between two nodes in the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_unlink_nodes","description":"Always \"bkn_unlink_nodes\" for this variant."},"arguments":{"type":"object","properties":{"source_name":{"type":"string","description":"Name or UUID of the source node."},"target_name":{"type":"string","description":"Name or UUID of the target node."},"relationship_type":{"type":"string","description":"Optional relationship type."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["source_name","target_name"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_get_subgraph","type":"object","description":"Invoke **bkn_get_subgraph**: Retrieve nodes scoped to a parent_uuid (or root if omitted) for fractal subgraph exploration.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_get_subgraph","description":"Always \"bkn_get_subgraph\" for this variant."},"arguments":{"type":"object","properties":{"parent_uuid":{"type":"string","description":"Optional parent node UUID. Omit or pass null to fetch top-level root nodes."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call agent_traverse_node","type":"object","description":"Invoke **agent_traverse_node**: Move an autonomous agent along a connected edge to a neighboring node, updating its topological location and streaming its traversal trail.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"agent_traverse_node","description":"Always \"agent_traverse_node\" for this variant."},"arguments":{"type":"object","properties":{"target_node_uuid":{"type":"string","description":"UUID of the destination node."},"reason":{"type":"string","description":"Reason or operational intent for traversing to this node."},"agent_id":{"type":"string","description":"Optional agent ID."}},"required":["target_node_uuid"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_emit_signal","type":"object","description":"Invoke **bkn_emit_signal**: Emit an active graph signal onto a target node or the workspace, broadcasting across the graph and alerting resident agents.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_emit_signal","description":"Always \"bkn_emit_signal\" for this variant."},"arguments":{"type":"object","properties":{"title":{"type":"string","description":"Title of the signal (e.g. 'Auth Rate Limit Exceeded' or 'MRR Milestone Achieved')."},"target_node_uuid":{"type":"string","description":"Optional UUID of the target knowledge node to attach this signal to."},"severity":{"type":"string","enum":["info","warning","critical","success"],"description":"Severity level of the signal (default: 'info')."},"signal_type":{"type":"string","description":"Category of signal: 'agent_alert', 'metric_threshold', 'webhook_event', 'human_blocker', 'temporal_deadline'."},"description":{"type":"string","description":"Detailed diagnostic narrative or explanation."},"propagation_mode":{"type":"string","enum":["local","downstream","upstream","broadcast"],"description":"Propagation ripple mode across graph topology (default: 'local')."},"payload":{"type":"object","description":"Arbitrary structured JSON metadata/diagnostics."},"is_persistent":{"type":"boolean","description":"If true, also mirrors as a persistent Signal node in the Knowledge Graph."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["title"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_resolve_signal","type":"object","description":"Invoke **bkn_resolve_signal**: Mark an active graph signal as resolved, recording resolution notes and timestamps.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_resolve_signal","description":"Always \"bkn_resolve_signal\" for this variant."},"arguments":{"type":"object","properties":{"signal_uuid":{"type":"string","description":"UUID of the signal to resolve."},"resolution_note":{"type":"string","description":"Explanation of how the alert/blocker was resolved."}},"required":["signal_uuid"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_list_signals","type":"object","description":"Invoke **bkn_list_signals**: List active and unacknowledged signals for the workspace or a specific node, ordered by severity.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_list_signals","description":"Always \"bkn_list_signals\" for this variant."},"arguments":{"type":"object","properties":{"target_node_uuid":{"type":"string","description":"Optional UUID of the node to filter signals for."},"limit":{"type":"number","description":"Maximum number of signals to retrieve (default: 50)."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}}}}},"required":["jsonrpc","method","params"]}]}}}},"responses":{"200":{"description":"Tool result, wrapped in a JSON-RPC 2.0 success envelope.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcSuccess"}}}},"400":{"description":"Parse error: the request body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"401":{"description":"Missing, invalid, or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"403":{"description":"The key lacks the scope required by the requested tool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"404":{"description":"Unknown tool name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"405":{"description":"Method not allowed. `GET` and `DELETE` are not offered because this transport is stateless — use `POST` for every request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded for this IP address or workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}}},"500":{"description":"Unhandled server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}}},"/api/mcp/messages":{"post":{"tags":["MCP Tools"],"summary":"Execute an MCP tool (JSON-RPC 2.0)","description":"Standard MCP tool execution endpoint. Send a JSON-RPC 2.0 `tools/call` request whose `params.name` is one of: `bkn_list_workspaces`, `bkn_create_workspace`, `bkn_query_graph`, `bkn_ingest_content`, `bkn_create_node`, `bkn_link_nodes`, `bkn_get_workspace_context`, `bkn_push_telemetry`, `bkn_mutate_variable`, `bkn_delete_node`, `bkn_unlink_nodes`, `bkn_get_subgraph`, `agent_traverse_node`, `bkn_emit_signal`, `bkn_resolve_signal`, `bkn_list_signals`.\n\nFor ChatGPT Custom GPT Actions, `POST /api/mcp/messages/{tool}` accepts the tool arguments directly, without the JSON-RPC envelope.","operationId":"executeMcpTool","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Select the variant matching the tool you want to call. Each variant fixes `params.name` and exposes that tool's argument schema.","anyOf":[{"title":"Call bkn_list_workspaces","type":"object","description":"Invoke **bkn_list_workspaces**: List all available workspaces in Blueprint Nexus with their node counts, descriptions, and modification timestamps.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_list_workspaces","description":"Always \"bkn_list_workspaces\" for this variant."},"arguments":{"type":"object","properties":{"limit":{"type":"number","description":"Maximum number of workspaces to return (default: 10)."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_create_workspace","type":"object","description":"Invoke **bkn_create_workspace**: Create a new project workspace in Blueprint Nexus with automatic registration of ownership, workspace settings, documentation, and initial Knowledge Graph (BKN) nodes.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_create_workspace","description":"Always \"bkn_create_workspace\" for this variant."},"arguments":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the workspace (required)."},"description":{"type":"string","description":"Charter, vision, or architectural summary of the workspace."},"problem_statement":{"type":"string","description":"Core problem or market opportunity addressed by this workspace."},"target_audience":{"type":"string","description":"Target user personas, market segment, or customer profiles."},"technologies":{"type":"array","items":{"type":"string"},"description":"Tech stack, frameworks, or tools used in this workspace."},"scope":{"type":"string","enum":["small","medium","large"],"description":"Estimated scope or scale (default: 'medium')."},"key_features":{"type":"array","items":{"type":"string"},"description":"Key product capabilities or deliverables."},"work_mode":{"type":"string","enum":["solo","team","swarm"],"description":"Workspace collaboration mode (default: 'solo')."},"created_by":{"type":"string","description":"Optional UUID of the user who owns this workspace. Defaults to API key owner or admin."},"initial_nodes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object"}},"required":["name","label"]},"description":"Optional array of initial Knowledge Graph nodes to seed into the workspace BKN."}},"required":["name"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_query_graph","type":"object","description":"Invoke **bkn_query_graph**: Search and retrieve nodes and edges from the workspace Knowledge Graph (BKN). Returns nodes, properties, and typed relationships.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_query_graph","description":"Always \"bkn_query_graph\" for this variant."},"arguments":{"type":"object","properties":{"query":{"type":"string","description":"Optional text query to match node names, descriptions, or properties."},"label":{"type":"string","description":"Optional category filter: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"limit":{"type":"number","description":"Max number of nodes to return (default: 50)."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_ingest_content","type":"object","description":"Invoke **bkn_ingest_content**: Universal Graph Ingestion engine. Analyzes raw unstructured text, application logs, specs, or code snippets, extracts entities and relationships, and automatically upserts them into the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_ingest_content","description":"Always \"bkn_ingest_content\" for this variant."},"arguments":{"type":"object","properties":{"content":{"type":"string","description":"The raw text, markdown document, code, or unstructured string to ingest into the Knowledge Graph."},"source_name":{"type":"string","description":"Name or identifier of the source (e.g., 'mobile-app-logs', 'linear-webhook', 'user-doc.md')."},"source_type":{"type":"string","description":"Category of the source (default: 'mcp_external_app')."}},"required":["content"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_create_node","type":"object","description":"Invoke **bkn_create_node**: Explicitly create or update a single Knowledge Node in the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_create_node","description":"Always \"bkn_create_node\" for this variant."},"arguments":{"type":"object","properties":{"name":{"type":"string","description":"Name or title of the node (e.g., 'Auth Token Expiration Exception')."},"label":{"type":"string","description":"Taxonomy label for the node: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"description":{"type":"string","description":"Detailed description or context for this node."},"metadata":{"type":"object","description":"Optional key-value JSON object containing custom properties, external IDs, or telemetry."}},"required":["name","label","description"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_link_nodes","type":"object","description":"Invoke **bkn_link_nodes**: Create a directed, typed edge between two existing nodes in the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_link_nodes","description":"Always \"bkn_link_nodes\" for this variant."},"arguments":{"type":"object","properties":{"source_name":{"type":"string","description":"Name of the source node."},"target_name":{"type":"string","description":"Name of the target node."},"relationship_type":{"type":"string","description":"Type of relationship: 'governs', 'decided_by', 'supports', 'conflicts_with', 'implements', 'supersedes', 'aligns', 'requires', 'blocks', 'triggers', 'references'."},"description":{"type":"string","description":"Rationale or explanation of why these nodes are linked."}},"required":["source_name","target_name","relationship_type"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_get_workspace_context","type":"object","description":"Invoke **bkn_get_workspace_context**: Fetch comprehensive context about the workspace, including executive summary, tech spec, open user stories, tasks, and key Knowledge Graph nodes.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_get_workspace_context","description":"Always \"bkn_get_workspace_context\" for this variant."},"arguments":{"type":"object","properties":{"include_docs":{"type":"boolean","description":"Whether to include full technical spec and executive summary (default: true)."},"include_tasks":{"type":"boolean","description":"Whether to include task epics and milestones (default: true)."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_push_telemetry","type":"object","description":"Invoke **bkn_push_telemetry**: Stream runtime telemetry, errors, or application events from an external app directly into the workspace's activity and audit log.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_push_telemetry","description":"Always \"bkn_push_telemetry\" for this variant."},"arguments":{"type":"object","properties":{"event_name":{"type":"string","description":"Short event identifier (e.g. 'payment_gateway_timeout', 'user_signup_failed')."},"severity":{"type":"string","description":"Severity level: 'info', 'warning', 'error', 'critical'."},"payload":{"type":"object","description":"JSON payload containing diagnostic data, stack trace, or state variables."}},"required":["event_name","payload"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_mutate_variable","type":"object","description":"Invoke **bkn_mutate_variable**: Mutate a Variable Node (e.g. increment daily push-ups counter, toggle smart light switch, or reset state) in the workspace Knowledge Graph. Automatically evaluates and fires connected reactive edge triggers.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_mutate_variable","description":"Always \"bkn_mutate_variable\" for this variant."},"arguments":{"type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the Variable Node to mutate."},"operation":{"type":"string","enum":["increment","decrement","set","toggle","reset"],"description":"Mutation operation to perform."},"amount":{"type":"number","description":"Optional numeric step for increment/decrement (default: 1)."},"value":{"description":"New value when using the 'set' operation."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier","operation"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_delete_node","type":"object","description":"Invoke **bkn_delete_node**: Delete or archive a node in the workspace Knowledge Graph (BKN) and sever all connected relationships.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_delete_node","description":"Always \"bkn_delete_node\" for this variant."},"arguments":{"type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the node to delete."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_unlink_nodes","type":"object","description":"Invoke **bkn_unlink_nodes**: Delete a directed relationship (edge) between two nodes in the workspace Knowledge Graph.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_unlink_nodes","description":"Always \"bkn_unlink_nodes\" for this variant."},"arguments":{"type":"object","properties":{"source_name":{"type":"string","description":"Name or UUID of the source node."},"target_name":{"type":"string","description":"Name or UUID of the target node."},"relationship_type":{"type":"string","description":"Optional relationship type."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["source_name","target_name"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_get_subgraph","type":"object","description":"Invoke **bkn_get_subgraph**: Retrieve nodes scoped to a parent_uuid (or root if omitted) for fractal subgraph exploration.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_get_subgraph","description":"Always \"bkn_get_subgraph\" for this variant."},"arguments":{"type":"object","properties":{"parent_uuid":{"type":"string","description":"Optional parent node UUID. Omit or pass null to fetch top-level root nodes."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}}}}},"required":["jsonrpc","method","params"]},{"title":"Call agent_traverse_node","type":"object","description":"Invoke **agent_traverse_node**: Move an autonomous agent along a connected edge to a neighboring node, updating its topological location and streaming its traversal trail.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"agent_traverse_node","description":"Always \"agent_traverse_node\" for this variant."},"arguments":{"type":"object","properties":{"target_node_uuid":{"type":"string","description":"UUID of the destination node."},"reason":{"type":"string","description":"Reason or operational intent for traversing to this node."},"agent_id":{"type":"string","description":"Optional agent ID."}},"required":["target_node_uuid"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_emit_signal","type":"object","description":"Invoke **bkn_emit_signal**: Emit an active graph signal onto a target node or the workspace, broadcasting across the graph and alerting resident agents.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_emit_signal","description":"Always \"bkn_emit_signal\" for this variant."},"arguments":{"type":"object","properties":{"title":{"type":"string","description":"Title of the signal (e.g. 'Auth Rate Limit Exceeded' or 'MRR Milestone Achieved')."},"target_node_uuid":{"type":"string","description":"Optional UUID of the target knowledge node to attach this signal to."},"severity":{"type":"string","enum":["info","warning","critical","success"],"description":"Severity level of the signal (default: 'info')."},"signal_type":{"type":"string","description":"Category of signal: 'agent_alert', 'metric_threshold', 'webhook_event', 'human_blocker', 'temporal_deadline'."},"description":{"type":"string","description":"Detailed diagnostic narrative or explanation."},"propagation_mode":{"type":"string","enum":["local","downstream","upstream","broadcast"],"description":"Propagation ripple mode across graph topology (default: 'local')."},"payload":{"type":"object","description":"Arbitrary structured JSON metadata/diagnostics."},"is_persistent":{"type":"boolean","description":"If true, also mirrors as a persistent Signal node in the Knowledge Graph."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["title"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_resolve_signal","type":"object","description":"Invoke **bkn_resolve_signal**: Mark an active graph signal as resolved, recording resolution notes and timestamps.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_resolve_signal","description":"Always \"bkn_resolve_signal\" for this variant."},"arguments":{"type":"object","properties":{"signal_uuid":{"type":"string","description":"UUID of the signal to resolve."},"resolution_note":{"type":"string","description":"Explanation of how the alert/blocker was resolved."}},"required":["signal_uuid"]}}}},"required":["jsonrpc","method","params"]},{"title":"Call bkn_list_signals","type":"object","description":"Invoke **bkn_list_signals**: List active and unacknowledged signals for the workspace or a specific node, ordered by severity.","properties":{"jsonrpc":{"type":"string","const":"2.0","description":"Always \"2.0\"."},"id":{"type":"number","description":"Request identifier echoed back in the response."},"method":{"type":"string","const":"tools/call","description":"Always \"tools/call\"."},"params":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string","const":"bkn_list_signals","description":"Always \"bkn_list_signals\" for this variant."},"arguments":{"type":"object","properties":{"target_node_uuid":{"type":"string","description":"Optional UUID of the node to filter signals for."},"limit":{"type":"number","description":"Maximum number of signals to retrieve (default: 50)."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}}}}},"required":["jsonrpc","method","params"]}]}}}},"responses":{"200":{"description":"Tool result, wrapped in a JSON-RPC 2.0 success envelope.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcSuccess"}}}},"400":{"description":"Parse error: the request body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"401":{"description":"Missing, invalid, or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"403":{"description":"The key lacks the scope required by the requested tool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"404":{"description":"Unknown tool name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"429":{"description":"Rate limit exceeded for this IP address or workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}}},"500":{"description":"Unhandled server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}}},"/api/mcp/messages/{tool}":{"post":{"tags":["MCP Tools"],"summary":"Execute one MCP tool by name","description":"ChatGPT-Action–optimized endpoint: send only the tool arguments as a JSON object. A full JSON-RPC 2.0 body is also accepted for backwards compatibility.","operationId":"executeNamedMcpTool","security":[{"BearerAuth":[]}],"parameters":[{"name":"tool","in":"path","required":true,"description":"Registered MCP tool name.","schema":{"type":"string","enum":["bkn_list_workspaces","bkn_create_workspace","bkn_query_graph","bkn_ingest_content","bkn_create_node","bkn_link_nodes","bkn_get_workspace_context","bkn_push_telemetry","bkn_mutate_variable","bkn_delete_node","bkn_unlink_nodes","bkn_get_subgraph","agent_traverse_node","bkn_emit_signal","bkn_resolve_signal","bkn_list_signals"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Arguments for the tool named in the path, or a full JSON-RPC 2.0 envelope.","anyOf":[{"title":"bkn_list_workspaces arguments","description":"Arguments for **bkn_list_workspaces**: List all available workspaces in Blueprint Nexus with their node counts, descriptions, and modification timestamps.","type":"object","properties":{"limit":{"type":"number","description":"Maximum number of workspaces to return (default: 10)."}}},{"title":"bkn_create_workspace arguments","description":"Arguments for **bkn_create_workspace**: Create a new project workspace in Blueprint Nexus with automatic registration of ownership, workspace settings, documentation, and initial Knowledge Graph (BKN) nodes.","type":"object","properties":{"name":{"type":"string","description":"Name or title of the workspace (required)."},"description":{"type":"string","description":"Charter, vision, or architectural summary of the workspace."},"problem_statement":{"type":"string","description":"Core problem or market opportunity addressed by this workspace."},"target_audience":{"type":"string","description":"Target user personas, market segment, or customer profiles."},"technologies":{"type":"array","items":{"type":"string"},"description":"Tech stack, frameworks, or tools used in this workspace."},"scope":{"type":"string","enum":["small","medium","large"],"description":"Estimated scope or scale (default: 'medium')."},"key_features":{"type":"array","items":{"type":"string"},"description":"Key product capabilities or deliverables."},"work_mode":{"type":"string","enum":["solo","team","swarm"],"description":"Workspace collaboration mode (default: 'solo')."},"created_by":{"type":"string","description":"Optional UUID of the user who owns this workspace. Defaults to API key owner or admin."},"initial_nodes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object"}},"required":["name","label"]},"description":"Optional array of initial Knowledge Graph nodes to seed into the workspace BKN."}},"required":["name"]},{"title":"bkn_query_graph arguments","description":"Arguments for **bkn_query_graph**: Search and retrieve nodes and edges from the workspace Knowledge Graph (BKN). Returns nodes, properties, and typed relationships.","type":"object","properties":{"query":{"type":"string","description":"Optional text query to match node names, descriptions, or properties."},"label":{"type":"string","description":"Optional category filter: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"limit":{"type":"number","description":"Max number of nodes to return (default: 50)."}}},{"title":"bkn_ingest_content arguments","description":"Arguments for **bkn_ingest_content**: Universal Graph Ingestion engine. Analyzes raw unstructured text, application logs, specs, or code snippets, extracts entities and relationships, and automatically upserts them into the workspace Knowledge Graph.","type":"object","properties":{"content":{"type":"string","description":"The raw text, markdown document, code, or unstructured string to ingest into the Knowledge Graph."},"source_name":{"type":"string","description":"Name or identifier of the source (e.g., 'mobile-app-logs', 'linear-webhook', 'user-doc.md')."},"source_type":{"type":"string","description":"Category of the source (default: 'mcp_external_app')."}},"required":["content"]},{"title":"bkn_create_node arguments","description":"Arguments for **bkn_create_node**: Explicitly create or update a single Knowledge Node in the workspace Knowledge Graph.","type":"object","properties":{"name":{"type":"string","description":"Name or title of the node (e.g., 'Auth Token Expiration Exception')."},"label":{"type":"string","description":"Taxonomy label for the node: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"description":{"type":"string","description":"Detailed description or context for this node."},"metadata":{"type":"object","description":"Optional key-value JSON object containing custom properties, external IDs, or telemetry."}},"required":["name","label","description"]},{"title":"bkn_link_nodes arguments","description":"Arguments for **bkn_link_nodes**: Create a directed, typed edge between two existing nodes in the workspace Knowledge Graph.","type":"object","properties":{"source_name":{"type":"string","description":"Name of the source node."},"target_name":{"type":"string","description":"Name of the target node."},"relationship_type":{"type":"string","description":"Type of relationship: 'governs', 'decided_by', 'supports', 'conflicts_with', 'implements', 'supersedes', 'aligns', 'requires', 'blocks', 'triggers', 'references'."},"description":{"type":"string","description":"Rationale or explanation of why these nodes are linked."}},"required":["source_name","target_name","relationship_type"]},{"title":"bkn_get_workspace_context arguments","description":"Arguments for **bkn_get_workspace_context**: Fetch comprehensive context about the workspace, including executive summary, tech spec, open user stories, tasks, and key Knowledge Graph nodes.","type":"object","properties":{"include_docs":{"type":"boolean","description":"Whether to include full technical spec and executive summary (default: true)."},"include_tasks":{"type":"boolean","description":"Whether to include task epics and milestones (default: true)."}}},{"title":"bkn_push_telemetry arguments","description":"Arguments for **bkn_push_telemetry**: Stream runtime telemetry, errors, or application events from an external app directly into the workspace's activity and audit log.","type":"object","properties":{"event_name":{"type":"string","description":"Short event identifier (e.g. 'payment_gateway_timeout', 'user_signup_failed')."},"severity":{"type":"string","description":"Severity level: 'info', 'warning', 'error', 'critical'."},"payload":{"type":"object","description":"JSON payload containing diagnostic data, stack trace, or state variables."}},"required":["event_name","payload"]},{"title":"bkn_mutate_variable arguments","description":"Arguments for **bkn_mutate_variable**: Mutate a Variable Node (e.g. increment daily push-ups counter, toggle smart light switch, or reset state) in the workspace Knowledge Graph. Automatically evaluates and fires connected reactive edge triggers.","type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the Variable Node to mutate."},"operation":{"type":"string","enum":["increment","decrement","set","toggle","reset"],"description":"Mutation operation to perform."},"amount":{"type":"number","description":"Optional numeric step for increment/decrement (default: 1)."},"value":{"description":"New value when using the 'set' operation."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier","operation"]},{"title":"bkn_delete_node arguments","description":"Arguments for **bkn_delete_node**: Delete or archive a node in the workspace Knowledge Graph (BKN) and sever all connected relationships.","type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the node to delete."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier"]},{"title":"bkn_unlink_nodes arguments","description":"Arguments for **bkn_unlink_nodes**: Delete a directed relationship (edge) between two nodes in the workspace Knowledge Graph.","type":"object","properties":{"source_name":{"type":"string","description":"Name or UUID of the source node."},"target_name":{"type":"string","description":"Name or UUID of the target node."},"relationship_type":{"type":"string","description":"Optional relationship type."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["source_name","target_name"]},{"title":"bkn_get_subgraph arguments","description":"Arguments for **bkn_get_subgraph**: Retrieve nodes scoped to a parent_uuid (or root if omitted) for fractal subgraph exploration.","type":"object","properties":{"parent_uuid":{"type":"string","description":"Optional parent node UUID. Omit or pass null to fetch top-level root nodes."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}},{"title":"agent_traverse_node arguments","description":"Arguments for **agent_traverse_node**: Move an autonomous agent along a connected edge to a neighboring node, updating its topological location and streaming its traversal trail.","type":"object","properties":{"target_node_uuid":{"type":"string","description":"UUID of the destination node."},"reason":{"type":"string","description":"Reason or operational intent for traversing to this node."},"agent_id":{"type":"string","description":"Optional agent ID."}},"required":["target_node_uuid"]},{"title":"bkn_emit_signal arguments","description":"Arguments for **bkn_emit_signal**: Emit an active graph signal onto a target node or the workspace, broadcasting across the graph and alerting resident agents.","type":"object","properties":{"title":{"type":"string","description":"Title of the signal (e.g. 'Auth Rate Limit Exceeded' or 'MRR Milestone Achieved')."},"target_node_uuid":{"type":"string","description":"Optional UUID of the target knowledge node to attach this signal to."},"severity":{"type":"string","enum":["info","warning","critical","success"],"description":"Severity level of the signal (default: 'info')."},"signal_type":{"type":"string","description":"Category of signal: 'agent_alert', 'metric_threshold', 'webhook_event', 'human_blocker', 'temporal_deadline'."},"description":{"type":"string","description":"Detailed diagnostic narrative or explanation."},"propagation_mode":{"type":"string","enum":["local","downstream","upstream","broadcast"],"description":"Propagation ripple mode across graph topology (default: 'local')."},"payload":{"type":"object","description":"Arbitrary structured JSON metadata/diagnostics."},"is_persistent":{"type":"boolean","description":"If true, also mirrors as a persistent Signal node in the Knowledge Graph."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["title"]},{"title":"bkn_resolve_signal arguments","description":"Arguments for **bkn_resolve_signal**: Mark an active graph signal as resolved, recording resolution notes and timestamps.","type":"object","properties":{"signal_uuid":{"type":"string","description":"UUID of the signal to resolve."},"resolution_note":{"type":"string","description":"Explanation of how the alert/blocker was resolved."}},"required":["signal_uuid"]},{"title":"bkn_list_signals arguments","description":"Arguments for **bkn_list_signals**: List active and unacknowledged signals for the workspace or a specific node, ordered by severity.","type":"object","properties":{"target_node_uuid":{"type":"string","description":"Optional UUID of the node to filter signals for."},"limit":{"type":"number","description":"Maximum number of signals to retrieve (default: 50)."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}}]}}}},"responses":{"200":{"description":"Tool result, wrapped in a JSON-RPC 2.0 success envelope.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcSuccess"}}}},"400":{"description":"Parse error: the request body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"401":{"description":"Missing, invalid, or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"403":{"description":"The key lacks the scope required by the requested tool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"404":{"description":"Unknown tool name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"429":{"description":"Rate limit exceeded for this IP address or workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}}},"500":{"description":"Unhandled server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}}},"/api/mcp/sse":{"get":{"tags":["Connection"],"summary":"Open the MCP server-sent-events stream","description":"Establishes an SSE connection for streaming MCP clients (Cursor, Claude Desktop, Smithery). The first event is `endpoint` with the messages URL to POST tool calls to.","operationId":"connectMcpSse","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"SSE stream. First event is `endpoint`.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"text/event-stream":{"schema":{"type":"string","example":"event: endpoint\ndata: https://www.bluesc.org/api/mcp/messages?session_id=…\n\n"}}}},"401":{"description":"Missing or invalid workspace API key.","content":{"text/plain":{"schema":{"type":"string","example":"Unauthorized: Invalid API key"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute per IP address or per key).","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"text/plain":{"schema":{"type":"string","example":"Rate limit exceeded"}}}}}}},"/api/mcp/ingest":{"post":{"tags":["Ingestion"],"summary":"Ingest text into the knowledge graph (REST)","description":"Sends raw text, markdown, or a JSON payload into the workspace knowledge graph. Accepts `application/json` (`{ content, source_name?, source_type? }`) or a plain text body. Maximum payload size is 500,000 characters.","operationId":"ingestUserContent","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRequest"}},"text/plain":{"schema":{"type":"string","description":"Raw text to ingest."}}}},"responses":{"200":{"description":"Ingestion completed.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestSuccess"}}}},"400":{"description":"Malformed request or missing required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"401":{"description":"Not signed in, or the workspace API key is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"403":{"description":"Not permitted: workspace ownership or plan tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"404":{"description":"Resource not found for this credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"429":{"description":"Rate limit exceeded for this IP address or workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}}},"500":{"description":"Unhandled server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}},"/api/mcp/connect":{"get":{"tags":["Connection"],"summary":"Read the current MCP connection state","description":"Reports the caller's tier, MCP entitlement, and workspace list. Authenticated by session cookie; returns `authenticated: false` for anonymous callers rather than an error.","operationId":"getMcpConnectionState","responses":{"200":{"description":"Connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectionState"}}}},"500":{"description":"Failed to retrieve connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}},"post":{"tags":["Connection"],"summary":"Provision a workspace API key for an MCP client","description":"Creates a scoped `bsc_live_…` workspace API key and returns ready-made client configuration. Requires a session cookie and an MCP-entitled tier (Hobby or above).","operationId":"provisionMcpConnection","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectRequest"}}}},"responses":{"200":{"description":"Connection provisioned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectResult"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"403":{"description":"Plan does not include MCP access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"404":{"description":"Requested workspace not found or not owned by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"500":{"description":"Unexpected error while provisioning the connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}},"/api/mcp/keys":{"get":{"tags":["Connection"],"summary":"List workspace API keys","description":"Lists key metadata (never the secret) for a workspace the caller owns.","operationId":"listWorkspaceApiKeys","parameters":[{"name":"workspace_id","in":"query","required":true,"description":"Workspace whose key metadata should be listed.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Key metadata plus the MCP server URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"400":{"description":"`workspace_id` query parameter is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"403":{"description":"Workspace not found or not owned by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"500":{"description":"Unexpected error while listing keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}},"post":{"tags":["Connection"],"summary":"Create a workspace API key","description":"Issues a new scoped key. The secret is returned exactly once.","operationId":"createWorkspaceApiKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateRequest"}}}},"responses":{"200":{"description":"Key created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"400":{"description":"Invalid or missing key parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"403":{"description":"Plan does not include MCP access, or the workspace is not owned by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}},"delete":{"tags":["Connection"],"summary":"Revoke a workspace API key","description":"Deletes a workspace API key the caller owns. Send the key id as the `id` query parameter.","operationId":"revokeWorkspaceApiKey","parameters":[{"name":"id","in":"query","required":true,"description":"Id of the key to revoke.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Key revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"`id` query parameter is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"404":{"description":"Key not found or not owned by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}},"500":{"description":"Unexpected error while revoking the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}},"/api/mcp/openapi":{"get":{"tags":["Discovery"],"summary":"Workspace-scoped OpenAPI document with one path per MCP tool","description":"Returns this same surface expanded so every MCP tool has its own `POST` path and named schemas — the form ChatGPT Custom GPT Actions import directly.","operationId":"getWorkspaceOpenApiDocument","parameters":[{"name":"workspace_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Workspace the generated document tailors its server URLs and examples to."}],"responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"`workspace_id` query parameter is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleError"}}}}}}}},"components":{"headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window. 60 for both the per-IP and the per-workspace-key MCP limits.","schema":{"type":"integer","example":60}},"RateLimit-Remaining":{"description":"Requests left in the current window. Read this and back off before it reaches 0 instead of waiting for a 429.","schema":{"type":"integer","example":42}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":37}},"RateLimit-Policy":{"description":"The policy in force, `\"<limit>;w=<window-seconds>\"` — for the MCP tool surface, `\"60;w=60\"` (60 requests per 60-second window).","schema":{"type":"string","example":"60;w=60"}},"Retry-After":{"description":"Seconds to wait before retrying. Present on 429 responses.","schema":{"type":"integer","example":37}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"bsc_live_…","description":"Workspace API key issued from `/api/mcp/connect` or `/api/mcp/keys`, sent as `Authorization: Bearer bsc_live_…`."}},"schemas":{"SimpleError":{"type":"object","description":"Error envelope used by the REST-style endpoints: a single human-readable message. Still JSON, never HTML — but prefer `ApiError` where an endpoint returns it.","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."},"retryAfterMs":{"type":"number","description":"Present on 429 responses."},"needs_upgrade":{"type":"boolean","description":"Present when the plan tier blocks the call."},"current_tier":{"type":"string","description":"Present alongside `needs_upgrade`."}}},"ApiError":{"type":"object","description":"Canonical structured error envelope: stable `code` to branch on, human `message`, a `hint` describing how to correct the request, and a `docs` pointer at this document.","required":["error"],"properties":{"error":{"type":"object","required":["code","message","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","enum":["not_found","method_not_allowed","bad_request","unauthorized","forbidden","internal_error"]},"message":{"type":"string","description":"Human-readable summary."},"hint":{"type":"string","description":"How to correct the request."},"docs":{"type":"string","default":"/openapi.json","description":"Path to this specification."}}}}},"JsonRpcSuccess":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":"number"},"result":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"text"},"text":{"type":"string","description":"Tool result, JSON-encoded."}}}},"isError":{"type":"boolean"}}}}},"JsonRpcError":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","example":-32601},"message":{"type":"string"},"data":{"description":"Optional structured detail."}}}}},"IngestRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Raw text, markdown, or code to ingest."},"source_name":{"type":"string","description":"Identifier of the calling app, e.g. \"chatgpt-custom-gpt\"."},"source_type":{"type":"string","description":"Source classification.","default":"external_app"}}},"IngestSuccess":{"type":"object","properties":{"success":{"type":"boolean"},"workspace_id":{"type":"string","format":"uuid"},"nodes_inserted":{"type":"number"},"edges_inserted":{"type":"number"},"message":{"type":"string"}}},"McpConnectionState":{"type":"object","properties":{"authenticated":{"type":"boolean"},"user":{"oneOf":[{"type":"null"},{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}}}]},"tier":{"type":"string"},"has_mcp":{"type":"boolean"},"trial_eligible":{"type":"boolean"},"trial_active":{"type":"boolean"},"workspaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"default_workspace_id":{"type":["string","null"],"format":"uuid"}}},"McpConnectRequest":{"type":"object","properties":{"client_name":{"type":"string","description":"Label for the key, e.g. \"Cursor\"."},"workspace_id":{"type":"string","format":"uuid","description":"Target workspace; defaults to the caller's first."},"start_trial":{"type":"boolean","description":"Claim the one-time MCP trial when the tier lacks MCP access."}}},"McpConnectResult":{"type":"object","properties":{"success":{"type":"boolean"},"token":{"type":"string","description":"The `bsc_live_…` secret. Returned exactly once."},"key_prefix":{"type":"string"},"workspace_id":{"type":"string","format":"uuid"},"workspace_name":{"type":"string"},"tier":{"type":"string"},"remote_mcp_server_url":{"type":"string","format":"uri"},"remote_mcp_messages_url":{"type":"string","format":"uri"},"claude_desktop_config":{"type":"object"},"cursor_install_url":{"type":"string"},"message":{"type":"string"}}},"WorkspaceApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key_name":{"type":"string"},"key_prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ApiKeyList":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceApiKey"}},"remote_mcp_server_url":{"type":"string","format":"uri"},"remote_mcp_messages_url":{"type":"string","format":"uri"}}},"ApiKeyCreateRequest":{"type":"object","required":["workspace_id","key_name"],"properties":{"workspace_id":{"type":"string","format":"uuid"},"key_name":{"type":"string","description":"Label for the key, truncated to 100 characters."},"scopes":{"type":"array","description":"Defaults to all scopes when omitted.","items":{"type":"string","enum":["bkn:read","bkn:write","bkn:ingest","mcp:tools"]}}}},"ApiKeyCreated":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/WorkspaceApiKey"},"secret_token":{"type":"string","description":"The `bsc_live_…` secret. Returned exactly once and never retrievable again."},"remote_mcp_server_url":{"type":"string","format":"uri"},"remote_mcp_messages_url":{"type":"string","format":"uri"},"message":{"type":"string"}}},"McpToolList":{"type":"array","description":"Tools currently registered by this API.","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}},"example":[{"name":"bkn_list_workspaces","description":"List all available workspaces in Blueprint Nexus with their node counts, descriptions, and modification timestamps."},{"name":"bkn_create_workspace","description":"Create a new project workspace in Blueprint Nexus with automatic registration of ownership, workspace settings, documentation, and initial Knowledge Graph (BKN) nodes."},{"name":"bkn_query_graph","description":"Search and retrieve nodes and edges from the workspace Knowledge Graph (BKN). Returns nodes, properties, and typed relationships."},{"name":"bkn_ingest_content","description":"Universal Graph Ingestion engine. Analyzes raw unstructured text, application logs, specs, or code snippets, extracts entities and relationships, and automatically upserts them into the workspace Knowledge Graph."},{"name":"bkn_create_node","description":"Explicitly create or update a single Knowledge Node in the workspace Knowledge Graph."},{"name":"bkn_link_nodes","description":"Create a directed, typed edge between two existing nodes in the workspace Knowledge Graph."},{"name":"bkn_get_workspace_context","description":"Fetch comprehensive context about the workspace, including executive summary, tech spec, open user stories, tasks, and key Knowledge Graph nodes."},{"name":"bkn_push_telemetry","description":"Stream runtime telemetry, errors, or application events from an external app directly into the workspace's activity and audit log."},{"name":"bkn_mutate_variable","description":"Mutate a Variable Node (e.g. increment daily push-ups counter, toggle smart light switch, or reset state) in the workspace Knowledge Graph. Automatically evaluates and fires connected reactive edge triggers."},{"name":"bkn_delete_node","description":"Delete or archive a node in the workspace Knowledge Graph (BKN) and sever all connected relationships."},{"name":"bkn_unlink_nodes","description":"Delete a directed relationship (edge) between two nodes in the workspace Knowledge Graph."},{"name":"bkn_get_subgraph","description":"Retrieve nodes scoped to a parent_uuid (or root if omitted) for fractal subgraph exploration."},{"name":"agent_traverse_node","description":"Move an autonomous agent along a connected edge to a neighboring node, updating its topological location and streaming its traversal trail."},{"name":"bkn_emit_signal","description":"Emit an active graph signal onto a target node or the workspace, broadcasting across the graph and alerting resident agents."},{"name":"bkn_resolve_signal","description":"Mark an active graph signal as resolved, recording resolution notes and timestamps."},{"name":"bkn_list_signals","description":"List active and unacknowledged signals for the workspace or a specific node, ordered by severity."}]},"ToolArgs_BknListWorkspaces":{"title":"bkn_list_workspaces arguments","description":"List all available workspaces in Blueprint Nexus with their node counts, descriptions, and modification timestamps.","type":"object","properties":{"limit":{"type":"number","description":"Maximum number of workspaces to return (default: 10)."}}},"ToolArgs_BknCreateWorkspace":{"title":"bkn_create_workspace arguments","description":"Create a new project workspace in Blueprint Nexus with automatic registration of ownership, workspace settings, documentation, and initial Knowledge Graph (BKN) nodes.","type":"object","properties":{"name":{"type":"string","description":"Name or title of the workspace (required)."},"description":{"type":"string","description":"Charter, vision, or architectural summary of the workspace."},"problem_statement":{"type":"string","description":"Core problem or market opportunity addressed by this workspace."},"target_audience":{"type":"string","description":"Target user personas, market segment, or customer profiles."},"technologies":{"type":"array","items":{"type":"string"},"description":"Tech stack, frameworks, or tools used in this workspace."},"scope":{"type":"string","enum":["small","medium","large"],"description":"Estimated scope or scale (default: 'medium')."},"key_features":{"type":"array","items":{"type":"string"},"description":"Key product capabilities or deliverables."},"work_mode":{"type":"string","enum":["solo","team","swarm"],"description":"Workspace collaboration mode (default: 'solo')."},"created_by":{"type":"string","description":"Optional UUID of the user who owns this workspace. Defaults to API key owner or admin."},"initial_nodes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object"}},"required":["name","label"]},"description":"Optional array of initial Knowledge Graph nodes to seed into the workspace BKN."}},"required":["name"]},"ToolArgs_BknQueryGraph":{"title":"bkn_query_graph arguments","description":"Search and retrieve nodes and edges from the workspace Knowledge Graph (BKN). Returns nodes, properties, and typed relationships.","type":"object","properties":{"query":{"type":"string","description":"Optional text query to match node names, descriptions, or properties."},"label":{"type":"string","description":"Optional category filter: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"limit":{"type":"number","description":"Max number of nodes to return (default: 50)."}}},"ToolArgs_BknIngestContent":{"title":"bkn_ingest_content arguments","description":"Universal Graph Ingestion engine. Analyzes raw unstructured text, application logs, specs, or code snippets, extracts entities and relationships, and automatically upserts them into the workspace Knowledge Graph.","type":"object","properties":{"content":{"type":"string","description":"The raw text, markdown document, code, or unstructured string to ingest into the Knowledge Graph."},"source_name":{"type":"string","description":"Name or identifier of the source (e.g., 'mobile-app-logs', 'linear-webhook', 'user-doc.md')."},"source_type":{"type":"string","description":"Category of the source (default: 'mcp_external_app')."}},"required":["content"]},"ToolArgs_BknCreateNode":{"title":"bkn_create_node arguments","description":"Explicitly create or update a single Knowledge Node in the workspace Knowledge Graph.","type":"object","properties":{"name":{"type":"string","description":"Name or title of the node (e.g., 'Auth Token Expiration Exception')."},"label":{"type":"string","description":"Taxonomy label for the node: 'Rule', 'Decision', 'Insight', 'Concept' (or execution types 'Goal', 'Task', 'Resource', 'Signal')."},"description":{"type":"string","description":"Detailed description or context for this node."},"metadata":{"type":"object","description":"Optional key-value JSON object containing custom properties, external IDs, or telemetry."}},"required":["name","label","description"]},"ToolArgs_BknLinkNodes":{"title":"bkn_link_nodes arguments","description":"Create a directed, typed edge between two existing nodes in the workspace Knowledge Graph.","type":"object","properties":{"source_name":{"type":"string","description":"Name of the source node."},"target_name":{"type":"string","description":"Name of the target node."},"relationship_type":{"type":"string","description":"Type of relationship: 'governs', 'decided_by', 'supports', 'conflicts_with', 'implements', 'supersedes', 'aligns', 'requires', 'blocks', 'triggers', 'references'."},"description":{"type":"string","description":"Rationale or explanation of why these nodes are linked."}},"required":["source_name","target_name","relationship_type"]},"ToolArgs_BknGetWorkspaceContext":{"title":"bkn_get_workspace_context arguments","description":"Fetch comprehensive context about the workspace, including executive summary, tech spec, open user stories, tasks, and key Knowledge Graph nodes.","type":"object","properties":{"include_docs":{"type":"boolean","description":"Whether to include full technical spec and executive summary (default: true)."},"include_tasks":{"type":"boolean","description":"Whether to include task epics and milestones (default: true)."}}},"ToolArgs_BknPushTelemetry":{"title":"bkn_push_telemetry arguments","description":"Stream runtime telemetry, errors, or application events from an external app directly into the workspace's activity and audit log.","type":"object","properties":{"event_name":{"type":"string","description":"Short event identifier (e.g. 'payment_gateway_timeout', 'user_signup_failed')."},"severity":{"type":"string","description":"Severity level: 'info', 'warning', 'error', 'critical'."},"payload":{"type":"object","description":"JSON payload containing diagnostic data, stack trace, or state variables."}},"required":["event_name","payload"]},"ToolArgs_BknMutateVariable":{"title":"bkn_mutate_variable arguments","description":"Mutate a Variable Node (e.g. increment daily push-ups counter, toggle smart light switch, or reset state) in the workspace Knowledge Graph. Automatically evaluates and fires connected reactive edge triggers.","type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the Variable Node to mutate."},"operation":{"type":"string","enum":["increment","decrement","set","toggle","reset"],"description":"Mutation operation to perform."},"amount":{"type":"number","description":"Optional numeric step for increment/decrement (default: 1)."},"value":{"description":"New value when using the 'set' operation."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier","operation"]},"ToolArgs_BknDeleteNode":{"title":"bkn_delete_node arguments","description":"Delete or archive a node in the workspace Knowledge Graph (BKN) and sever all connected relationships.","type":"object","properties":{"node_identifier":{"type":"string","description":"UUID or exact name of the node to delete."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["node_identifier"]},"ToolArgs_BknUnlinkNodes":{"title":"bkn_unlink_nodes arguments","description":"Delete a directed relationship (edge) between two nodes in the workspace Knowledge Graph.","type":"object","properties":{"source_name":{"type":"string","description":"Name or UUID of the source node."},"target_name":{"type":"string","description":"Name or UUID of the target node."},"relationship_type":{"type":"string","description":"Optional relationship type."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["source_name","target_name"]},"ToolArgs_BknGetSubgraph":{"title":"bkn_get_subgraph arguments","description":"Retrieve nodes scoped to a parent_uuid (or root if omitted) for fractal subgraph exploration.","type":"object","properties":{"parent_uuid":{"type":"string","description":"Optional parent node UUID. Omit or pass null to fetch top-level root nodes."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}},"ToolArgs_AgentTraverseNode":{"title":"agent_traverse_node arguments","description":"Move an autonomous agent along a connected edge to a neighboring node, updating its topological location and streaming its traversal trail.","type":"object","properties":{"target_node_uuid":{"type":"string","description":"UUID of the destination node."},"reason":{"type":"string","description":"Reason or operational intent for traversing to this node."},"agent_id":{"type":"string","description":"Optional agent ID."}},"required":["target_node_uuid"]},"ToolArgs_BknEmitSignal":{"title":"bkn_emit_signal arguments","description":"Emit an active graph signal onto a target node or the workspace, broadcasting across the graph and alerting resident agents.","type":"object","properties":{"title":{"type":"string","description":"Title of the signal (e.g. 'Auth Rate Limit Exceeded' or 'MRR Milestone Achieved')."},"target_node_uuid":{"type":"string","description":"Optional UUID of the target knowledge node to attach this signal to."},"severity":{"type":"string","enum":["info","warning","critical","success"],"description":"Severity level of the signal (default: 'info')."},"signal_type":{"type":"string","description":"Category of signal: 'agent_alert', 'metric_threshold', 'webhook_event', 'human_blocker', 'temporal_deadline'."},"description":{"type":"string","description":"Detailed diagnostic narrative or explanation."},"propagation_mode":{"type":"string","enum":["local","downstream","upstream","broadcast"],"description":"Propagation ripple mode across graph topology (default: 'local')."},"payload":{"type":"object","description":"Arbitrary structured JSON metadata/diagnostics."},"is_persistent":{"type":"boolean","description":"If true, also mirrors as a persistent Signal node in the Knowledge Graph."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}},"required":["title"]},"ToolArgs_BknResolveSignal":{"title":"bkn_resolve_signal arguments","description":"Mark an active graph signal as resolved, recording resolution notes and timestamps.","type":"object","properties":{"signal_uuid":{"type":"string","description":"UUID of the signal to resolve."},"resolution_note":{"type":"string","description":"Explanation of how the alert/blocker was resolved."}},"required":["signal_uuid"]},"ToolArgs_BknListSignals":{"title":"bkn_list_signals arguments","description":"List active and unacknowledged signals for the workspace or a specific node, ordered by severity.","type":"object","properties":{"target_node_uuid":{"type":"string","description":"Optional UUID of the node to filter signals for."},"limit":{"type":"number","description":"Maximum number of signals to retrieve (default: 50)."},"workspace_id":{"type":"string","description":"Optional workspace UUID."}}}}}}