secondbrainos-mcp-server 1.5.4 → 1.7.0

package/README.md

@@ -25,8 +25,8 @@ secondbrainos-mcp USER_ID USER_SECRET
 This will:
 1. Verify your account credentials
 2. Confirm you have access to the Claude MCP feature
-3. Create the necessary configuration files for Claude Desktop
-4. Configure the server to dynamically fetch your available API endpoints
+3. Store credentials securely at `~/.secondbrainos/credentials.json`
+4. Configure Claude Desktop and Claude Code to use `serve` mode (credentials read from file, not embedded in config)
 
 ### Claude Code
 
@@ -52,16 +52,20 @@ The server uses `@samchon/openapi` library for robust OpenAPI handling, providin
 - Support for complex parameters and nested objects
 
 ### Prompts
-The server exposes three types of MCP prompts, available in the client's attach menu:
+The server exposes four types of MCP prompts, available as slash commands (e.g. `/secondbrainos:agent_my_agent`):
+
+#### Start (`start_secondbrainos`)
+- Returns a context document with SBOS terminology, agent architecture, and an index of all available agents and skills with their slash commands
+- Useful for orienting Claude at the start of a session
 
 #### Skills (Workflows)
-- Automatically discovers your workflows via the `runPromptChain` service
+- Discovered via `runPromptChain` on first `ListPrompts` call, then cached for the session
 - Each skill appears with a `[Skill]` prefix and returns a structured document with `skill_id`, `name`, `description`, and an ordered list of prompts (metadata only, no instructions)
 - Supports an optional `user_input` argument to provide additional context
 
 #### Agents
-- Discovers your AI agents via the `getAIAgentsSchema` service
-- Each agent appears with an `[Agent]` prefix and returns a structured document containing `agent_id`, `name`, `description`, `behaviour_and_instructions`, `searchMyKnowledge_collection_id`, `actions` (with id, name, description, body_parameters), and `workflows` (with enriched prompt metadata)
+- Discovered via `getAIAgentsSchema` on first `ListPrompts` call, then cached for the session
+- Each agent appears with an `[Agent]` prefix and returns a structured document containing `agent_id`, `name`, `description`, `behaviour_and_instructions`, `searchMyKnowledge_collection_id`, `actions` (with id, name, description, body_parameters), and `workflows` (with prompt order and description)
 - Supports an optional `user_input` argument
 
 #### Knowledge Bases
@@ -132,20 +136,29 @@ secondbrainos-mcp-server/
 └── README.md            # This file
 ```
 
-## Environment Variables
+## Credentials
 
-The server requires the following environment variables:
-- `USER_ID`: Your Second Brain OS user ID
-- `USER_SECRET`: Your Second Brain OS user secret
-- `API_BASE_URL` (optional): Override the default API base URL
+Credentials are stored securely at `~/.secondbrainos/credentials.json` (created during setup with mode `0o600`). The server reads from this file in `serve` mode. Environment variables `USER_ID`, `USER_SECRET`, and `API_BASE_URL` can override the stored credentials if set.
 
 ## How It Works
 
-1. **Schema Fetching**: On startup, the server fetches your personalized OpenAPI schema from Second Brain OS
+1. **Schema Fetching**: On startup, the server fetches your personalized OpenAPI schema from `schema.secondbrainos.com`
 2. **Schema Conversion**: The `@samchon/openapi` library converts the schema to an optimized format for LLM function calling
 3. **MCP Tools**: Each API endpoint becomes an MCP tool that Claude can use
-4. **MCP Prompts**: Your skills (workflows), AI agents, and knowledge bases are exposed as selectable prompts in the client UI
-5. **Function Execution**: When Claude calls a tool, the server executes the corresponding API call with proper authentication
+4. **MCP Prompts**: On first `ListPrompts` call (automatic on session connect), the server fetches all agents via `getAIAgentsSchema` and all workflows via `runPromptChain`, caches them in memory, and exposes them as slash commands
+5. **Slash Commands**: When a user runs a slash command (e.g. `/secondbrainos:agent_my_agent`), the server returns the full agent/skill definition from cache — no additional API calls, no credit cost
+6. **Function Execution**: When Claude calls a tool, the server executes the corresponding API call via `api.secondbrainos.com` with proper authentication
+7. **File Upload**: Local file paths in tool arguments are automatically uploaded to GCS via signed URL before the API call
+
+### Credit Cost
+
+| Event | Credits |
+|-------|---------|
+| Session init | n workflows + n agents |
+| Slash commands | 0 (cached) |
+| Tool calls | Billed per call via service router |
+
+See [`docs/architecture.md`](docs/architecture.md) for detailed diagrams.
 
 ## Troubleshooting
 

package/bin/cli.js

@@ -332,13 +332,12 @@ async function main() {
     const hadExistingSecondBrainOS = !!existingConfig.mcpServers.secondbrainos;
 
     // Add or update the secondbrainos server configuration
+    // Uses serve mode which reads credentials from ~/.secondbrainos/credentials.json
+    const cliPath = path.join(packageRoot, 'bin', 'cli.js');
     existingConfig.mcpServers.secondbrainos = {
       command: nodePath,
-      args: [serverPath],
+      args: [cliPath, 'serve'],
       env: {
-        USER_ID,
-        USER_SECRET,
-        API_BASE_URL: 'https://api.secondbrainos.com',
         NODE_PATH: getNodeModulesPath()
       }
     };
@@ -362,42 +361,6 @@ async function main() {
     const cliPath = path.join(packageRoot, 'bin', 'cli.js');
     const claudeCodeConfigured = await configureClaudeCode(cliPath, nodePath);
 
-    // Add SessionStart hook to global Claude Code settings
-    if (claudeCodeConfigured) {
-      try {
-        const claudeSettingsPath = path.join(homedir(), '.claude', 'settings.json');
-        let settings = {};
-        try {
-          settings = JSON.parse(await fs.readFile(claudeSettingsPath, 'utf8'));
-        } catch { /* file may not exist yet */ }
-
-        if (!settings.hooks) settings.hooks = {};
-        if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
-
-        // Check if our hook already exists
-        const skillFilePath = path.join(homedir(), '.claude', 'skills', 'secondbrainos', 'server-use', 'SKILL.md');
-        const hookCommand = `cat "${skillFilePath}" 2>/dev/null || true`;
-        const hasHook = settings.hooks.SessionStart.some(
-          entry => entry.hooks && entry.hooks.some(h => h.command && h.command.includes('secondbrainos/server-use/SKILL.md'))
-        );
-
-        if (!hasHook) {
-          settings.hooks.SessionStart.push({
-            hooks: [
-              {
-                type: "command",
-                command: hookCommand
-              }
-            ]
-          });
-          await fs.writeFile(claudeSettingsPath, JSON.stringify(settings, null, 2));
-          console.log('SessionStart hook configured for SBOS context loading.');
-        }
-      } catch (error) {
-        console.log(`Note: Could not configure SessionStart hook: ${error.message}`);
-      }
-    }
-
     console.log('\nInstallation successful!');
     console.log('\nClaude Desktop:');
     console.log('1. Completely quit Claude Desktop if it is running');

package/build/index.js

@@ -5,9 +5,8 @@ import { OpenApi, HttpLlm } from "@samchon/openapi";
 import axios from "axios";
 import dotenv from "dotenv";
 import yaml from 'js-yaml';
-import fs from 'fs';
 import path from 'path';
-import { homedir } from 'os';
+import fs from 'fs';
 dotenv.config();
 function toSnakeCase(str) {
     return str
@@ -15,12 +14,6 @@ function toSnakeCase(str) {
         .replace(/[^a-z0-9]+/g, '_')
         .replace(/^_+|_+$/g, '');
 }
-function toKebabCase(str) {
-    return str
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
 class SecondBrainOSServer {
     constructor(initialSchema) {
         this.originalSpec = initialSchema;
@@ -80,7 +73,7 @@ class SecondBrainOSServer {
                 tools: {},
                 prompts: {}
             },
-            instructions: "SBOS provides tools for managing knowledge along with definitions for sub-agents and associated skills. For full server context, see the skills at ~/.claude/skills/secondbrainos/"
+            instructions: "SBOS provides tools for managing knowledge along with definitions for sub-agents and associated skills. Run /secondbrainos:start_secondbrainos to load full SBOS context."
         });
         this.setupHandlers();
         this.setupErrorHandling();
@@ -253,6 +246,13 @@ class SecondBrainOSServer {
                     console.error('Failed to fetch agents for prompts/list:', error);
                 }
             }
+            // Add start_secondbrainos prompt — returns the server-use context document
+            prompts.push({
+                name: "start_secondbrainos",
+                title: "[Start] Second Brain OS",
+                description: "Load SBOS context: terminology, architecture, and available agents & skills index",
+                arguments: []
+            });
             // Add Knowledge Bases prompt (collects searchMyKnowledge_collection_ids from agents)
             if (this.getAIAgentsSchemaPath) {
                 try {
@@ -285,6 +285,22 @@ class SecondBrainOSServer {
         this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
             const promptName = request.params.name;
             const userInput = request.params.arguments?.user_input;
+            // Check if this is the start_secondbrainos prompt
+            if (promptName === "start_secondbrainos") {
+                const content = await this.buildServerUseContent();
+                return {
+                    description: "Second Brain OS — Server Context",
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: content
+                            }
+                        }
+                    ]
+                };
+            }
             // Check if this is the Knowledge Bases prompt
             if (promptName === "knowledge_bases") {
                 const agents = await this.fetchAndEnrichAgents();
@@ -322,23 +338,14 @@ class SecondBrainOSServer {
             if (agentId) {
                 return this.buildAgentPrompt(agentId, userInput);
             }
-            // Otherwise treat as a workflow prompt
+            // Otherwise treat as a workflow prompt — use cached data
             const workflowId = this.workflowNameToId.get(promptName) || promptName;
-            // Single call — list response now includes prompt metadata per workflow
-            const workflowsData = await this.callRunPromptChain('', '');
-            const workflowMeta = (workflowsData.workflows || []).find((wf) => wf.workflow_id === workflowId);
-            const prompts = workflowMeta?.prompts || [];
-            if (prompts.length === 0) {
+            const workflows = await this.fetchAndEnrichWorkflows();
+            const workflowMeta = workflows.find((wf) => wf.workflow_id === workflowId);
+            if (!workflowMeta || !workflowMeta.prompts || workflowMeta.prompts.length === 0) {
                 throw new McpError(ErrorCode.InvalidRequest, `No prompts found for workflow: ${workflowId}`);
             }
-            const sortedPrompts = prompts
-                .map((p) => ({
-                id: p.prompt_id,
-                name: p.name || '',
-                order: p.order || 0,
-                description: p.description || ''
-            }))
-                .sort((a, b) => (a.order || 0) - (b.order || 0));
+            const sortedPrompts = workflowMeta.prompts;
             const workflowDocument = {
                 skill_id: workflowId,
                 name: workflowMeta?.name || promptName,
@@ -418,15 +425,12 @@ class SecondBrainOSServer {
             messages
         };
     }
-    async callRunPromptChain(entity, entityId) {
+    async callRunPromptChain() {
         if (!this.runPromptChainPath) {
             throw new McpError(ErrorCode.InternalError, 'runPromptChain service not available for this user');
         }
         const url = `${this.baseUrl}${this.runPromptChainPath}`;
-        const response = await axios.post(url, {
-            entity,
-            entity_id: entityId
-        }, {
+        const response = await axios.post(url, {}, {
             headers: {
                 'Authorization': `Bearer ${this.userId}:${this.userSecret}`,
                 'Content-Type': 'application/json'
@@ -523,20 +527,10 @@ class SecondBrainOSServer {
     async fetchAndEnrichAgents() {
         if (this.cachedAgents)
             return this.cachedAgents;
-        // Fetch agents and all workflows in parallel
-        const [agentData, workflows] = await Promise.all([
-            this.callGetAIAgentsSchema(),
-            this.fetchAndEnrichWorkflows()
-        ]);
+        // Single API call — getAIAgentsSchema now returns prompt order/description
+        const agentData = await this.callGetAIAgentsSchema();
         const agents = agentData.agents || [];
-        // Build a prompt lookup from the already-fetched workflows
-        const promptLookup = new Map();
-        for (const wf of workflows) {
-            for (const p of wf.prompts || []) {
-                promptLookup.set(p.id, p);
-            }
-        }
-        // Enrich agent workflows using the lookup — no extra API calls
+        // Sort prompts within each workflow by order
         for (const agent of agents) {
             if (!agent.workflows)
                 continue;
@@ -544,16 +538,13 @@ class SecondBrainOSServer {
                 if (!workflow.prompts || workflow.prompts.length === 0)
                     continue;
                 workflow.prompts = workflow.prompts
-                    .map((prompt) => {
-                    const enriched = promptLookup.get(prompt.id);
-                    return {
-                        id: prompt.id,
-                        name: enriched?.name || prompt.name,
-                        order: enriched?.order || 0,
-                        description: enriched?.description || ''
-                    };
-                })
-                    .sort((a, b) => (a.order || 0) - (b.order || 0));
+                    .map((prompt) => ({
+                    id: prompt.id,
+                    name: prompt.name || '',
+                    order: prompt.order || 0,
+                    description: prompt.description || ''
+                }))
+                    .sort((a, b) => (Number(a.order) || 0) - (Number(b.order) || 0));
             }
         }
         this.cachedAgents = agents;
@@ -563,7 +554,7 @@ class SecondBrainOSServer {
         if (this.cachedWorkflows)
             return this.cachedWorkflows;
         // Single API call — now returns all workflows with prompt metadata
-        const data = await this.callRunPromptChain('', '');
+        const data = await this.callRunPromptChain();
         const workflows = (data.workflows || []).filter((wf) => wf.name && wf.workflow_id);
         const enriched = workflows.map((wf) => ({
             ...wf,
@@ -580,25 +571,17 @@ class SecondBrainOSServer {
         return enriched;
     }
     /**
-     * Write Claude Code skill files to ~/.claude/skills/secondbrainos/
-     * Called on every server startup so skills stay in sync with SBOS.
+     * Build the server-use context document content.
+     * Used by the start_secondbrainos prompt.
      */
-    async writeSkillFiles() {
-        const skillsBase = path.join(homedir(), '.claude', 'skills', 'secondbrainos');
-        // Helper to write a SKILL.md file
-        const writeSkill = (dir, content) => {
-            fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(path.join(dir, 'SKILL.md'), content, 'utf-8');
-        };
-        // 1. server-use — context document for Claude Code sessions
-        // Gather agent and workflow names for the index
+    async buildServerUseContent() {
         let agentIndex = '';
         let skillIndex = '';
         try {
             const agents = await this.fetchAndEnrichAgents();
             agentIndex = agents
                 .filter((a) => a.name && a.id)
-                .map((a) => `- ${a.name} → \`/secondbrainos:agent_${toSnakeCase(a.name)}\``)
+                .map((a) => `- ${a.name} (id: ${a.id}) → \`/secondbrainos:agent_${toSnakeCase(a.name)}\`${a.description ? `\n  ${a.description}` : ''}`)
                 .join('\n');
         }
         catch { /* skip if unavailable */ }
@@ -606,11 +589,11 @@ class SecondBrainOSServer {
             const workflows = await this.fetchAndEnrichWorkflows();
             skillIndex = workflows
                 .filter((wf) => wf.name)
-                .map((wf) => `- ${wf.name} → \`/secondbrainos:skill_${toSnakeCase(wf.name)}\``)
+                .map((wf) => `- ${wf.name} (id: ${wf.workflow_id}) → \`/secondbrainos:skill_${toSnakeCase(wf.name)}\`${wf.description ? `\n  ${wf.description}` : ''}`)
                 .join('\n');
         }
         catch { /* skip if unavailable */ }
-        const serverUseContent = `---
+        return `---
 name: server-use
 description: Second Brain OS server context — terminology, architecture, and available agents/skills index
 user-invocable: false
@@ -630,14 +613,13 @@ An agent definition combines:
 2. **Services (Tools)** — the MCP tools the agent can use
 3. **Workflows (Skills)** — the prompt chains the agent follows
 
-This means you can spin up sub-agents from an agent's skill definitions (see \`~/.claude/skills/secondbrainos/tabs/\`).
+## Loading Agent & Skill Details
+- To get full agent definitions (behaviour, knowledge, actions, workflows): use the \`getAIAgentsSchema\` tool
+- To get full skill/workflow details and run prompt chains: use the \`runPromptChain\` tool
 
 ## Accessing Agents & Skills
-- Skill files live at \`~/.claude/skills/secondbrainos/\` (tabs/, workflows/, knowledge-bases/)
-- All skill files are set to \`user-invocable: false\` to avoid duplicating slash commands already available via MCP prompts
 - **Users** invoke agents or skills via slash commands (e.g. \`/secondbrainos:agent_...\` or \`/secondbrainos:skill_...\`)
 - **Users** cannot invoke MCP tools directly via slash commands — they must ask you to load and call the relevant tool
-- When using an agent with sub-agents, load the necessary skills at the start of the conversation by reading the agent's skill files
 
 ## Available Agents
 ${agentIndex || '_None configured_'}
@@ -645,85 +627,12 @@ ${agentIndex || '_None configured_'}
 ## Available Skills
 ${skillIndex || '_None configured_'}
 `;
-        writeSkill(path.join(skillsBase, 'server-use'), serverUseContent);
-        // 2. tabs (agents)
-        if (this.getAIAgentsSchemaPath) {
-            try {
-                const agents = await this.fetchAndEnrichAgents();
-                for (const agent of agents) {
-                    if (!agent.name || !agent.id)
-                        continue;
-                    const folderName = toKebabCase(agent.name);
-                    const agentDocument = {
-                        agent_id: agent.id,
-                        name: agent.name,
-                        description: agent.description || '',
-                        behaviour_and_instructions: agent.behaviour_and_instructions || '',
-                        searchMyKnowledge_collection_id: agent.searchMyKnowledge_collection_id || '',
-                        actions: agent.actions || [],
-                        workflows: (agent.workflows || []).map((wf) => ({
-                            id: wf.id,
-                            name: wf.name,
-                            prompts: (wf.prompts || []).map((p) => ({
-                                id: p.id,
-                                name: p.name,
-                                order: p.order,
-                                description: p.description
-                            }))
-                        }))
-                    };
-                    writeSkill(path.join(skillsBase, 'tabs', folderName), `---\nname: ${folderName}\ndescription: "${agent.description || agent.name}"\nuser-invocable: false\n---\n\n${JSON.stringify(agentDocument, null, 2)}\n`);
-                }
-            }
-            catch (error) {
-                console.error('Failed to write agent skill files:', error);
-            }
-        }
-        // 3. workflows (uses cached enriched data)
-        if (this.runPromptChainPath) {
-            try {
-                const workflows = await this.fetchAndEnrichWorkflows();
-                for (const wf of workflows) {
-                    const folderName = toKebabCase(wf.name);
-                    const workflowDocument = {
-                        skill_id: wf.workflow_id,
-                        name: wf.name,
-                        description: wf.description || '',
-                        prompts: wf.prompts
-                    };
-                    writeSkill(path.join(skillsBase, 'workflows', folderName), `---\nname: ${folderName}\ndescription: "${wf.description || wf.name}"\nuser-invocable: false\n---\n\n${JSON.stringify(workflowDocument, null, 2)}\n`);
-                }
-            }
-            catch (error) {
-                console.error('Failed to write workflow skill files:', error);
-            }
-        }
-        // 4. knowledgebases
-        if (this.getAIAgentsSchemaPath) {
-            try {
-                const agents = await this.fetchAndEnrichAgents();
-                const collectionIds = agents
-                    .map((a) => a.searchMyKnowledge_collection_id)
-                    .filter((id) => id && id.length > 0);
-                if (collectionIds.length > 0) {
-                    const kbDocument = { searchMyKnowledge_collection_ids: collectionIds };
-                    writeSkill(path.join(skillsBase, 'knowledge-bases'), `---\nname: knowledge-bases\ndescription: Knowledge base collection IDs available to agents\nuser-invocable: false\n---\n\n${JSON.stringify(kbDocument, null, 2)}\n`);
-                }
-            }
-            catch (error) {
-                console.error('Failed to write knowledge bases skill file:', error);
-            }
-        }
-        console.error('Skill files written to ~/.claude/skills/secondbrainos/');
     }
     setupErrorHandling() {
         // Error handling is now built into HttpLlm.execute
         // This method is kept for future error handling implementations
     }
     async run() {
-        // Write skill files before connecting so Claude Code sees them at session start.
-        // This is fast now (~2-3s) since enrichment uses single API calls.
-        await this.writeSkillFiles().catch(err => console.error('Failed to write skill files:', err));
         const transport = new StdioServerTransport();
         await this.server.connect(transport);
         console.error("Second Brain OS MCP server running on stdio");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secondbrainos-mcp-server",
-  "version": "1.5.4",
+  "version": "1.7.0",
   "description": "Second Brain OS MCP Server for Claude Desktop",
   "type": "module",
   "main": "build/index.js",