secondbrainos-mcp-server 1.6.0 → 1.7.1

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()
       }
     };
@@ -359,7 +358,6 @@ async function main() {
     }
 
     // Configure Claude Code
-    const cliPath = path.join(packageRoot, 'bin', 'cli.js');
     const claudeCodeConfigured = await configureClaudeCode(cliPath, nodePath);
 
     console.log('\nInstallation successful!');

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
@@ -339,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,
@@ -435,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'
@@ -540,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;
@@ -561,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;
@@ -580,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,
@@ -596,20 +570,9 @@ class SecondBrainOSServer {
         this.cachedWorkflows = enriched;
         return enriched;
     }
-    /**
-     * Write the server-use skill file to ~/.claude/skills/secondbrainos/
-     * Called on every server startup so the context index stays in sync with SBOS.
-     */
-    async writeServerUseSkillFile() {
-        const serverUseContent = await this.buildServerUseContent();
-        const dir = path.join(homedir(), '.claude', 'skills', 'secondbrainos', 'server-use');
-        fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(path.join(dir, 'SKILL.md'), serverUseContent, 'utf-8');
-        console.error('Server-use skill file written to ~/.claude/skills/secondbrainos/server-use/');
-    }
     /**
      * Build the server-use context document content.
-     * Used by both writeServerUseSkillFile and the start_secondbrainos prompt.
+     * Used by the start_secondbrainos prompt.
      */
     async buildServerUseContent() {
         let agentIndex = '';
@@ -670,8 +633,6 @@ ${skillIndex || '_None configured_'}
         // This method is kept for future error handling implementations
     }
     async run() {
-        // Write server-use skill file before connecting so Claude Code sees it at session start.
-        await this.writeServerUseSkillFile().catch(err => console.error('Failed to write server-use skill file:', 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.6.0",
+  "version": "1.7.1",
   "description": "Second Brain OS MCP Server for Claude Desktop",
   "type": "module",
   "main": "build/index.js",