create-byan-agent 2.26.0 → 2.27.0

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -9,6 +9,7 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { dispatch } from './lib/dispatch.js';
+import { resolveConfig } from './lib/resolve-config.js';
 import { harvest as harvestInsights, renderDigest as renderInsightDigest } from './lib/insight-harvest.js';
 import { appendOutcome } from './lib/outcome-buffer.js';
 import { validateForLog, eloOutcomeForStrictComplete } from './lib/advisory-autofeed.js';
@@ -96,15 +97,33 @@ const __dirname = nodePath.dirname(__filename);
 // {projectRoot}/_byan/mcp/byan-mcp-server/server.js, so go up three levels.
 const PROJECT_ROOT = nodePath.resolve(__dirname, '..', '..', '..');
 
-const BYAN_API_URL = process.env.BYAN_API_URL || 'http://localhost:3737';
-const BYAN_API_TOKEN = process.env.BYAN_API_TOKEN || '';
+// Config resolution (F1): precedence process.env -> ~/.byan/credentials.json
+// -> localhost default, with an unexpanded ${..} env value treated as absent.
+// The resolver (lib/resolve-config.js) owns this so the server works regardless
+// of how it was launched (Claude Code ${} expansion, Codex, raw stdio) and
+// across shells/OSes. We backfill process.env with the resolved values so every
+// downstream reader (requireLeantime, the Leantime client) sees a real value
+// instead of the literal "${...}" placeholder that breaks byan_web calls.
+const RESOLVED_CONFIG = resolveConfig();
+for (const k of ['BYAN_API_URL', 'BYAN_API_TOKEN', 'LEANTIME_API_URL', 'LEANTIME_API_TOKEN']) {
+  if (RESOLVED_CONFIG[k]) process.env[k] = RESOLVED_CONFIG[k];
+}
 
-const authHeaders = () => {
-  if (!BYAN_API_TOKEN) return {};
+const BYAN_API_URL = RESOLVED_CONFIG.BYAN_API_URL;
+// Local-dev / single-user fallback token. On the remote HTTP transport the
+// real identity is the PER-REQUEST token (see createByanServer), so this env
+// value is only the floor when no per-request token is supplied (stdio).
+const ENV_API_TOKEN = RESOLVED_CONFIG.BYAN_API_TOKEN;
+
+// Per-call auth header builder. The token is passed EXPLICITLY (per-request on
+// the remote transport; the env token locally) so a shared connector process
+// never collapses every caller onto one identity.
+const authHeadersFor = (token) => {
+  if (!token) return {};
   // byan_web issues API keys prefixed with `byan_` and requires the
   // `ApiKey` scheme. Any other token (JWT, etc.) falls back to Bearer.
-  const scheme = BYAN_API_TOKEN.startsWith('byan_') ? 'ApiKey' : 'Bearer';
-  return { Authorization: `${scheme} ${BYAN_API_TOKEN}` };
+  const scheme = token.startsWith('byan_') ? 'ApiKey' : 'Bearer';
+  return { Authorization: `${scheme} ${token}` };
 };
 
 function buildQuery(params) {
@@ -117,8 +136,8 @@ function buildQuery(params) {
   return s ? `?${s}` : '';
 }
 
-function requireToken() {
-  if (!BYAN_API_TOKEN) {
+function requireTokenFor(token) {
+  if (!token) {
     throw new Error('BYAN_API_TOKEN env var is required for this tool.');
   }
 }
@@ -131,11 +150,11 @@ function requireLeantime() {
   }
 }
 
-async function apiRequest(path, options = {}) {
+async function apiRequestFor(path, options = {}, token) {
   const url = `${BYAN_API_URL}${path}`;
   const headers = {
     'Content-Type': 'application/json',
-    ...authHeaders(),
+    ...authHeadersFor(token),
     ...(options.headers || {}),
   };
   const res = await fetch(url, { ...options, headers });
@@ -935,56 +954,74 @@ const tools = [
   },
 
   // ─── Knowledge ────────────────────────────────────────────────────────
+  // Routes: GET /api/projects/:projectId/knowledge (RBAC viewer)
+  //         GET /api/projects/:projectId/knowledge/:id (RBAC viewer)
+  // The flat /api/knowledge surface was decommissioned (IDOR — no RBAC).
   {
     name: 'byan_api_knowledge_list',
     description:
-      'List knowledge entries, optionally filtered by project, category, tags, or limit. GET /api/knowledge. Requires BYAN_API_TOKEN.',
+      'List knowledge entries for a project. GET /api/projects/:projectId/knowledge. projectId is required (the flat /api/knowledge surface was decommissioned for IDOR). Requires BYAN_API_TOKEN.',
     inputSchema: {
       type: 'object',
       properties: {
-        projectId: { type: 'string' },
+        projectId: { type: 'string', description: 'Project id (required).' },
         category: { type: 'string' },
-        tags: { type: 'string', description: 'Comma-separated tag list.' },
+        tags: { type: 'string', description: 'Tag filter (substring match).' },
+        nodeId: { type: 'string', description: 'Filter by node id (includes child nodes).' },
         limit: { type: 'number' },
       },
+      required: ['projectId'],
       additionalProperties: false,
     },
   },
   {
     name: 'byan_api_knowledge_get',
     description:
-      'Fetch a single knowledge entry by id. GET /api/knowledge/:id. Requires BYAN_API_TOKEN.',
+      'Fetch a single knowledge entry by id within a project. GET /api/projects/:projectId/knowledge/:id. Both projectId and id are required (RBAC guard). Requires BYAN_API_TOKEN.',
     inputSchema: {
       type: 'object',
-      properties: { id: { type: 'string', description: 'Knowledge entry id.' } },
-      required: ['id'],
+      properties: {
+        projectId: { type: 'string', description: 'Project id (required for RBAC).' },
+        id: { type: 'string', description: 'Knowledge entry id.' },
+      },
+      required: ['projectId', 'id'],
       additionalProperties: false,
     },
   },
 
   // ─── Memory ───────────────────────────────────────────────────────────
+  // Route: GET /api/projects/:projectId/memory (RBAC viewer)
+  // The flat /api/memory surface was decommissioned (IDOR).
+  // Full-text memory search: use byan_api_search with q + project_id.
   {
     name: 'byan_api_memory_list',
     description:
-      'List memory entries, optionally filtered by project, category, type, or limit. GET /api/memory. Requires BYAN_API_TOKEN.',
+      'List memory entries for a project. GET /api/projects/:projectId/memory. projectId is required (the flat /api/memory surface was decommissioned for IDOR). Optionally filter by category, layer, nodeId, sessionId, limit, includePinned. Requires BYAN_API_TOKEN.',
     inputSchema: {
       type: 'object',
       properties: {
-        projectId: { type: 'string' },
+        projectId: { type: 'string', description: 'Project id (required).' },
         category: { type: 'string' },
-        type: { type: 'string' },
+        layer: { type: 'string', description: 'Memory layer filter (e.g. short_term, long_term).' },
+        nodeId: { type: 'string' },
+        sessionId: { type: 'string' },
+        includePinned: { type: 'boolean' },
         limit: { type: 'number' },
       },
+      required: ['projectId'],
       additionalProperties: false,
     },
   },
   {
     name: 'byan_api_memory_search',
     description:
-      'Full-text search across memory entries. GET /api/memory/search. Requires BYAN_API_TOKEN.',
+      'Full-text search over project knowledge and nodes (covers memory indirectly). Routes to GET /api/search?q=...&project_id=... — the dedicated /api/memory/search surface was decommissioned. For structured memory recall use byan_api_memory_list with category/layer filters. Requires BYAN_API_TOKEN.',
     inputSchema: {
       type: 'object',
-      properties: { q: { type: 'string', description: 'Search query.' } },
+      properties: {
+        q: { type: 'string', description: 'Search query.' },
+        projectId: { type: 'string', description: 'Optional project id to scope the search.' },
+      },
       required: ['q'],
       additionalProperties: false,
     },
@@ -1023,35 +1060,38 @@ const tools = [
   },
 
   // ─── Sessions ─────────────────────────────────────────────────────────
+  // Routes: GET /api/projects/:projectId/sessions (RBAC viewer)
+  //         GET /api/projects/:projectId/sessions/:id (RBAC viewer)
+  // The flat /api/sessions surface was decommissioned (IDOR).
+  // Note: there is no /history sub-route on project-scoped sessions;
+  // byan_api_sessions_history has been removed from this surface.
   {
     name: 'byan_api_sessions_list',
     description:
-      'List byan_web sessions, optionally filtered by project. GET /api/sessions. Requires BYAN_API_TOKEN.',
+      'List project sessions. GET /api/projects/:projectId/sessions. projectId is required (the flat /api/sessions surface was decommissioned for IDOR). Optionally filter by userId, cliSource, limit. Requires BYAN_API_TOKEN.',
     inputSchema: {
       type: 'object',
-      properties: { projectId: { type: 'string' } },
+      properties: {
+        projectId: { type: 'string', description: 'Project id (required).' },
+        userId: { type: 'string' },
+        cliSource: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      required: ['projectId'],
       additionalProperties: false,
     },
   },
   {
     name: 'byan_api_sessions_get',
     description:
-      'Fetch a single session by id. GET /api/sessions/:id. Requires BYAN_API_TOKEN.',
-    inputSchema: {
-      type: 'object',
-      properties: { id: { type: 'string', description: 'Session id.' } },
-      required: ['id'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'byan_api_sessions_history',
-    description:
-      'Fetch the message/event history of a session. GET /api/sessions/:id/history. Requires BYAN_API_TOKEN.',
+      'Fetch a single project session by id. GET /api/projects/:projectId/sessions/:id. Both projectId and id are required (RBAC guard). Requires BYAN_API_TOKEN.',
     inputSchema: {
       type: 'object',
-      properties: { id: { type: 'string', description: 'Session id.' } },
-      required: ['id'],
+      properties: {
+        projectId: { type: 'string', description: 'Project id (required for RBAC).' },
+        id: { type: 'string', description: 'Session id.' },
+      },
+      required: ['projectId', 'id'],
       additionalProperties: false,
     },
   },
@@ -1263,19 +1303,136 @@ const tools = [
       additionalProperties: false,
     },
   },
+
+  // ─── Styx discovery index (FD-2) ───────────────────────────────────────
+  {
+    name: 'byan_styx_atlas',
+    description:
+      'Styx atlas: a token-bounded map of the WHOLE byan_web ecosystem (projects, nodes, knowledge, workflows, agents) in one call. GET /api/styx/atlas. Returns dense STYX/1 text (one compact line per entity, not JSON-per-item) so you can locate anything cheaply, then descend with byan_styx_get. Aggregates hierarchically (projects + per-project counts + top-k children) and stops at maxTokens. Use this BEFORE list_projects + search when you want a cheap overview or to find an entity. Requires BYAN_API_TOKEN. Scoped to the caller\'s accessible projects (+ global).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: {
+          type: 'string',
+          enum: ['project', 'node', 'knowledge', 'workflow', 'agent'],
+          description: 'Optional: restrict the atlas to one entity kind.',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Optional: zoom into a single project instead of the ecosystem-wide view.',
+        },
+        maxTokens: {
+          type: 'number',
+          description: 'Token budget for the atlas (default 1500, server cap 4000). Out of [100,4000] -> INVALID_FORMAT.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'byan_styx_get',
+    description:
+      'Styx get: zoom into one entity and list its DIRECT children only (one level per call, fanout-bounded ~7). GET /api/styx/get. Use the id8 prefix (8 chars) or full uuid shown in the atlas, or "__global__" for the global node. Returns dense STYX/1 text + breadcrumb + footer (cursor for paging beyond fanout). This is the progressive descent companion of byan_styx_atlas. Requires BYAN_API_TOKEN. Entities outside accessible projects resolve as STYX_NOT_FOUND (no cross-tenant existence leak).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Entity id: id8 prefix, full uuid, or "__global__".',
+        },
+        fanout: {
+          type: 'number',
+          description: 'Number of direct children to return (default 7, cap 15).',
+        },
+        cursor: {
+          type: 'string',
+          description: 'Opaque pagination cursor returned in a previous footer to fetch the next page of children.',
+        },
+      },
+      required: ['id'],
+      additionalProperties: false,
+    },
+  },
 ];
 
-const server = new Server(
-  { name: 'byan-mcp', version: '0.1.0' },
-  { capabilities: { tools: {} } }
-);
+// Remote-safe MVP allowlist: the ONLY tools exposed on the remote Org Connector
+// (server-http.js sets remoteOnly:true). All are read-only and byan_web-backed
+// (already user-scoped server-side via the per-request token) with ZERO local
+// filesystem dependency, so they are safe on a shared multi-tenant host. Every
+// fs-local / stateful / write / import tool is excluded and stays stdio-only.
+// The byan-lint-remote-safe check enforces that nothing fs-bound leaks in here.
+const REMOTE_SAFE_TOOLS = new Set([
+  'byan_ping',
+  'byan_list_projects',
+  'byan_api_projects_get',
+  'byan_api_workflows_list',
+  'byan_api_workflows_get',
+  'byan_api_workflow_runs_list',
+  'byan_api_workflow_runs_get',
+  'byan_api_knowledge_list',
+  'byan_api_knowledge_get',
+  'byan_api_memory_list',
+  'byan_api_memory_search',
+  'byan_api_custom_agents_list',
+  'byan_api_custom_agents_get',
+  'byan_api_sessions_list',
+  'byan_api_sessions_get',
+  'byan_api_chat_conversations_list',
+  'byan_api_chat_messages_list',
+  'byan_api_search',
+  'byan_styx_atlas',
+  'byan_styx_get',
+]);
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+// Resolve the effective byan_web token for a server instance. On the remote
+// transport (remoteOnly) the identity is the per-request token ONLY — it never
+// falls back to the host env token, so a no-header remote request resolves to
+// NO identity (the tool degrades with its requireToken error) instead of
+// silently borrowing the host's token. The local stdio path keeps the env
+// token as the single-developer fallback.
+export function resolveCallerToken({ token, remoteOnly, envToken }) {
+  if (remoteOnly) return token || undefined;
+  return token || envToken || undefined;
+}
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+// Build a fresh MCP Server with all tools + handlers registered, WITHOUT
+// connecting any transport. The stdio entrypoint (bottom of this file) and the
+// remote HTTP entrypoint (server-http.js) both call this factory, so the tool
+// surface stays single-sourced across transports. A fresh instance per call
+// keeps stateless HTTP requests from sharing in-process server state.
+export function createByanServer({ token, remoteOnly = false } = {}) {
+  // Per-request identity. `token` is the caller's token on the remote HTTP
+  // transport; it falls back to the env token for the local stdio path. Every
+  // tool handler below calls apiRequest / authHeaders / requireToken and reads
+  // BYAN_API_TOKEN — all of which resolve to THESE per-request bindings by
+  // lexical shadowing, so the ~70 call sites need no change and two concurrent
+  // callers on a shared connector never share an identity (GH#44980).
+  const BYAN_API_TOKEN = resolveCallerToken({ token, remoteOnly, envToken: ENV_API_TOKEN });
+  const authHeaders = () => authHeadersFor(BYAN_API_TOKEN);
+  const requireToken = () => requireTokenFor(BYAN_API_TOKEN);
+  const apiRequest = (path, options) => apiRequestFor(path, options, BYAN_API_TOKEN);
+
+  const server = new Server(
+    { name: 'byan-mcp', version: '0.1.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: remoteOnly ? tools.filter((t) => REMOTE_SAFE_TOOLS.has(t.name)) : tools,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
   try {
+    // The remote connector exposes ONLY the read-only MVP allowlist. A call to
+    // any other tool over the remote transport is refused as a per-tool error
+    // (normalized to { isError } by the catch below) — never a 500, never run.
+    if (remoteOnly && !REMOTE_SAFE_TOOLS.has(name)) {
+      throw new Error(
+        `Tool '${name}' is not available on the remote BYAN connector (read-only MVP surface).`
+      );
+    }
     if (name === 'byan_ping') {
       const t0 = Date.now();
       const body = await apiRequest('/api/health');
@@ -1738,38 +1895,50 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     if (name === 'byan_api_knowledge_list') {
       requireToken();
+      if (!args.projectId) throw new Error('projectId is required (RBAC: knowledge is project-scoped).');
       const qs = buildQuery({
-        project_id: args.projectId,
         category: args.category,
         tags: args.tags,
-        limit: args.limit,
+        nodeId: args.nodeId,
       });
-      const body = await apiRequest(`/api/knowledge${qs}`);
+      const body = await apiRequest(
+        `/api/projects/${encodeURIComponent(args.projectId)}/knowledge${qs}`
+      );
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
     if (name === 'byan_api_knowledge_get') {
       requireToken();
-      const body = await apiRequest(`/api/knowledge/${encodeURIComponent(args.id)}`);
+      if (!args.projectId) throw new Error('projectId is required (RBAC: knowledge is project-scoped).');
+      const body = await apiRequest(
+        `/api/projects/${encodeURIComponent(args.projectId)}/knowledge/${encodeURIComponent(args.id)}`
+      );
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
     if (name === 'byan_api_memory_list') {
       requireToken();
+      if (!args.projectId) throw new Error('projectId is required (RBAC: memory is project-scoped).');
       const qs = buildQuery({
-        project_id: args.projectId,
         category: args.category,
-        type: args.type,
+        layer: args.layer,
+        nodeId: args.nodeId,
+        sessionId: args.sessionId,
+        includePinned: args.includePinned,
         limit: args.limit,
       });
-      const body = await apiRequest(`/api/memory${qs}`);
+      const body = await apiRequest(
+        `/api/projects/${encodeURIComponent(args.projectId)}/memory${qs}`
+      );
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
     if (name === 'byan_api_memory_search') {
       requireToken();
-      const qs = buildQuery({ q: args.q });
-      const body = await apiRequest(`/api/memory/search${qs}`);
+      // /api/memory/search is decommissioned; full-text search routes through /api/search
+      // which covers knowledge + nodes across projects the caller can access.
+      const qs = buildQuery({ q: args.q, project_id: args.projectId });
+      const body = await apiRequest(`/api/search${qs}`);
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
@@ -1798,21 +1967,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     if (name === 'byan_api_sessions_list') {
       requireToken();
-      const qs = buildQuery({ project_id: args.projectId });
-      const body = await apiRequest(`/api/sessions${qs}`);
+      if (!args.projectId) throw new Error('projectId is required (RBAC: sessions are project-scoped).');
+      const qs = buildQuery({
+        userId: args.userId,
+        cliSource: args.cliSource,
+        limit: args.limit,
+      });
+      const body = await apiRequest(
+        `/api/projects/${encodeURIComponent(args.projectId)}/sessions${qs}`
+      );
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
     if (name === 'byan_api_sessions_get') {
       requireToken();
-      const body = await apiRequest(`/api/sessions/${encodeURIComponent(args.id)}`);
-      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
-    }
-
-    if (name === 'byan_api_sessions_history') {
-      requireToken();
+      if (!args.projectId) throw new Error('projectId is required (RBAC: sessions are project-scoped).');
       const body = await apiRequest(
-        `/api/sessions/${encodeURIComponent(args.id)}/history`
+        `/api/projects/${encodeURIComponent(args.projectId)}/sessions/${encodeURIComponent(args.id)}`
       );
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
@@ -1856,6 +2027,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
+    if (name === 'byan_styx_atlas') {
+      requireToken();
+      const qs = buildQuery({
+        kind: args.kind,
+        projectId: args.projectId,
+        maxTokens: args.maxTokens,
+      });
+      const body = await apiRequest(`/api/styx/atlas${qs}`);
+      // body.data is the dense STYX/1 text -- return it verbatim (the whole point
+      // of styx is token economy ; do not re-wrap each line as JSON).
+      return { content: [{ type: 'text', text: (body && body.data) || JSON.stringify(body, null, 2) }] };
+    }
+
+    if (name === 'byan_styx_get') {
+      requireToken();
+      const qs = buildQuery({
+        id: args.id,
+        fanout: args.fanout,
+        cursor: args.cursor,
+      });
+      const body = await apiRequest(`/api/styx/get${qs}`);
+      return { content: [{ type: 'text', text: (body && body.data) || JSON.stringify(body, null, 2) }] };
+    }
+
     if (name === 'byan_api_import_scan') {
       requireToken();
       // Build files payload from client filesystem — works for remote byan_web.
@@ -1976,9 +2171,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: 'text', text: `Error: ${err.message}` }],
     };
   }
-});
+  });
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+  return server;
+}
+
+// Stdio entrypoint guard: connect stdio ONLY when this file is the process
+// entrypoint (or explicitly forced). Importing the module (tests, the HTTP
+// entrypoint server-http.js) must NOT grab stdio as a side effect.
+const isStdioEntrypoint =
+  process.env.BYAN_MCP_TRANSPORT === 'stdio' ||
+  (process.argv[1] &&
+    nodePath.resolve(process.argv[1]) === nodePath.resolve(__filename));
+
+if (isStdioEntrypoint) {
+  const transport = new StdioServerTransport();
+  await createByanServer().connect(transport);
+}
 
-export { buildFilesPayload };
+export { buildFilesPayload, REMOTE_SAFE_TOOLS, authHeadersFor, BYAN_API_URL };