secondbrainos-mcp-server 1.2.3 → 1.2.5

package/README.md

@@ -1,11 +1,11 @@
 # Second Brain OS MCP Server
 
-This package provides a Model Context Protocol (MCP) server for integrating Second Brain OS with Claude Desktop.
+This package provides a Model Context Protocol (MCP) server for integrating Second Brain OS with Claude Desktop and Claude Code.
 
 ## Prerequisites
 
 - Node.js v16 or higher
-- Claude Desktop application
+- Claude Desktop application and/or Claude Code CLI
 - A valid Second Brain OS account with the Claude MCP feature enabled
 
 ## Installation
@@ -28,6 +28,16 @@ This will:
 3. Create the necessary configuration files for Claude Desktop
 4. Configure the server to dynamically fetch your available API endpoints
 
+### Claude Code
+
+To add the server to Claude Code:
+
+```bash
+claude mcp add secondbrainos-mcp-server -- npx secondbrainos-mcp-server
+```
+
+Or add it to your project's `.mcp.json` file.
+
 ## Features
 
 ### Enhanced OpenAPI Support
@@ -41,13 +51,23 @@ The server uses `@samchon/openapi` library for robust OpenAPI handling, providin
 - Automatic request formatting based on OpenAPI specifications
 - Support for complex parameters and nested objects
 
-### Prompts (Workflows)
-The server exposes your Second Brain OS workflows as MCP prompts, making them available in Claude Desktop's attach menu:
+### Prompts
+The server exposes three types of MCP prompts, available in the client's attach menu:
+
+#### Skills (Workflows)
 - Automatically discovers your workflows via the `runPromptChain` service
-- Each workflow appears as a selectable prompt with its name and description
-- Selecting a prompt fetches the full prompt chain (ordered instructions) and injects them into the conversation
+- 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)
+- Supports an optional `user_input` argument
+
+#### Knowledge Bases
+- Aggregates all `searchMyKnowledge_collection_id` values from your agents
+- Appears as a single `[Knowledge Bases]` prompt returning an array of collection IDs
+
 ### Better Error Handling
 - Detailed error messages for debugging
 - Proper handling of authentication failures, bad requests, and service errors
@@ -124,14 +144,14 @@ The server requires the following environment variables:
 1. **Schema Fetching**: On startup, the server fetches your personalized OpenAPI schema from Second Brain OS
 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**: If the `runPromptChain` service is available, your workflows are exposed as selectable prompts in the client UI
+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
 
 ## Troubleshooting
 
-### Claude Desktop doesn't see the server
-1. Ensure Claude Desktop is completely quit before running the setup
-2. Check the configuration file was created at the correct location
+### Client doesn't see the server
+1. **Claude Desktop**: Ensure it's completely quit before running setup. Check the configuration file was created at the correct location.
+2. **Claude Code**: Run `claude mcp add` or check your `.mcp.json` configuration.
 3. Review the logs at the platform-specific location mentioned during setup
 
 ### Authentication errors

package/bin/cli.js

@@ -129,13 +129,103 @@ async function readExistingConfig(configPath) {
   }
 }
 
+/**
+ * Get the credentials file path
+ */
+function getCredentialsPath() {
+  return path.join(homedir(), '.secondbrainos', 'credentials.json');
+}
+
+/**
+ * Store credentials to ~/.secondbrainos/credentials.json
+ */
+async function storeCredentials(USER_ID, USER_SECRET) {
+  const credDir = path.join(homedir(), '.secondbrainos');
+  await fs.mkdir(credDir, { recursive: true });
+  await fs.writeFile(
+    getCredentialsPath(),
+    JSON.stringify({ USER_ID, USER_SECRET, API_BASE_URL: 'https://api.secondbrainos.com' }, null, 2),
+    { mode: 0o600 }
+  );
+}
+
+/**
+ * Configure Claude Code via `claude mcp add`
+ */
+async function configureClaudeCode(serverPath, nodePath) {
+  try {
+    const { stdout } = await execAsync('which claude').catch(() => ({ stdout: '' }));
+    if (!stdout.trim()) {
+      console.log('\nClaude Code CLI not found — skipping Claude Code configuration.');
+      console.log('To set up Claude Code later, install it and run this setup again.');
+      return false;
+    }
+
+    // Remove existing config first (ignore errors if it doesn't exist)
+    await execAsync('claude mcp remove secondbrainos -s user').catch(() => {});
+
+    // Add the server with serve subcommand
+    await execAsync(`claude mcp add secondbrainos -s user -- ${nodePath} ${serverPath} serve`);
+    console.log('Claude Code configured successfully!');
+    return true;
+  } catch (error) {
+    console.log(`\nClaude Code auto-configuration failed: ${error.message}`);
+    console.log('You can manually configure it by running:');
+    console.log(`  claude mcp add secondbrainos -s user -- ${nodePath} ${serverPath} serve`);
+    return false;
+  }
+}
+
+/**
+ * Run the MCP server (serve mode)
+ */
+async function serve() {
+  // Load credentials from stored file, with env var override
+  let USER_ID = process.env.USER_ID;
+  let USER_SECRET = process.env.USER_SECRET;
+  let API_BASE_URL = process.env.API_BASE_URL;
+
+  if (!USER_ID || !USER_SECRET) {
+    try {
+      const creds = JSON.parse(await fs.readFile(getCredentialsPath(), 'utf8'));
+      USER_ID = USER_ID || creds.USER_ID;
+      USER_SECRET = USER_SECRET || creds.USER_SECRET;
+      API_BASE_URL = API_BASE_URL || creds.API_BASE_URL;
+    } catch {
+      console.error('Error: No credentials found. Run setup first:');
+      console.error('  npx secondbrainos-mcp-server USER_ID USER_SECRET');
+      process.exit(1);
+    }
+  }
+
+  if (!USER_ID || !USER_SECRET) {
+    console.error('Error: Missing USER_ID or USER_SECRET.');
+    process.exit(1);
+  }
+
+  // Set env vars for the server process
+  process.env.USER_ID = USER_ID;
+  process.env.USER_SECRET = USER_SECRET;
+  process.env.API_BASE_URL = API_BASE_URL || 'https://api.secondbrainos.com';
+
+  // Import and run the server
+  const packageRoot = path.resolve(__dirname, '..');
+  const serverModule = path.join(packageRoot, 'build', 'index.js');
+  await import(serverModule);
+}
+
 async function main() {
   try {
     // Get command line arguments
     const args = process.argv.slice(2);
-    
+
+    // Handle serve subcommand
+    if (args.length === 1 && args[0] === 'serve') {
+      return await serve();
+    }
+
     let USER_ID, USER_SECRET;
-    
+
     if (args.length === 1 && args[0].includes(':')) {
       // Handle the combined format USER_ID:USER_SECRET
       [USER_ID, USER_SECRET] = args[0].split(':');
@@ -145,70 +235,79 @@ async function main() {
     } else {
       console.error('Usage: secondbrainos-mcp USER_ID:USER_SECRET');
       console.error('   or: secondbrainos-mcp USER_ID USER_SECRET');
+      console.error('   or: secondbrainos-mcp serve');
       process.exit(1);
     }
-    
+
     // Validate that we have both values
     if (!USER_ID || !USER_SECRET) {
       console.error('Error: Both USER_ID and USER_SECRET are required');
       process.exit(1);
     }
-    
+
     console.log('Verifying user credentials...');
-    
+
     // Verify user with the cloud function
     try {
       const verificationUrl = 'https://us-central1-second-brain-os.cloudfunctions.net/gcf-sbos-verifyuserdatapublic';
       const response = await axios.post(verificationUrl, {
         "x-user-api-key": `Bearer ${USER_ID}:${USER_SECRET}`
       });
-      
+
       const { exists, email, features } = response.data;
-      
+
       if (!exists || exists !== 1) {
         console.error('Error: User does not exist.');
         process.exit(1);
       }
-      
+
       if (!email) {
         console.error('Error: User email not found.');
         process.exit(1);
       }
-      
+
       // Check if claudemcp feature is enabled
       if (!features || typeof features !== 'string') {
         console.error('Error: User features not found.');
         process.exit(1);
       }
-      
+
       const featuresList = features.toLowerCase().split(',').map(f => f.trim().replace(/\s+/g, ''));
       if (!featuresList.includes('claudemcp')) {
         console.error('Error: Claude MCP feature not enabled for this user.');
         process.exit(1);
       }
-      
+
       console.log('User verified successfully!');
-      
+
     } catch (error) {
       console.error('Error verifying user:', error.message);
       process.exit(1);
     }
-    
-    // Create Claude Desktop configuration directory if it doesn't exist
+
+    // Store credentials locally
+    try {
+      await storeCredentials(USER_ID, USER_SECRET);
+      console.log(`Credentials stored at: ${getCredentialsPath()}`);
+    } catch (error) {
+      console.error('Warning: Could not store credentials:', error.message);
+    }
+
+    // Configure Claude Desktop
     const claudeConfigDir = getClaudeConfigPath();
     const claudeConfigFile = path.join(claudeConfigDir, 'claude_desktop_config.json');
-    
+
     try {
       await fs.mkdir(claudeConfigDir, { recursive: true });
     } catch (error) {
       console.error('Error creating config directory:', error);
       process.exit(1);
     }
-    
+
     // Get the absolute path to the installed package's index.js file
     const packageRoot = path.resolve(__dirname, '..');
     const serverPath = path.join(packageRoot, 'build', 'index.js');
-    
+
     // Check if serverPath exists
     try {
       await fs.access(serverPath);
@@ -217,21 +316,21 @@ async function main() {
       console.error('This might be due to an incomplete installation. Try reinstalling the package with: npm install -g secondbrainos-mcp-server');
       process.exit(1);
     }
-    
+
     // Find Node.js executable
     const nodePath = await findNodeExecutable();
-    
+
     // Read existing configuration
     const existingConfig = await readExistingConfig(claudeConfigFile);
-    
+
     // Ensure mcpServers object exists
     if (!existingConfig.mcpServers) {
       existingConfig.mcpServers = {};
     }
-    
+
     // Check if secondbrainos already exists
     const hadExistingSecondBrainOS = !!existingConfig.mcpServers.secondbrainos;
-    
+
     // Add or update the secondbrainos server configuration
     existingConfig.mcpServers.secondbrainos = {
       command: nodePath,
@@ -243,30 +342,39 @@ async function main() {
         NODE_PATH: getNodeModulesPath()
       }
     };
-    
+
     try {
       // Write the updated configuration back
       await fs.writeFile(claudeConfigFile, JSON.stringify(existingConfig, null, 2));
-      console.log(`Configuration file ${hadExistingSecondBrainOS ? 'updated' : 'created'} at: ${claudeConfigFile}`);
-      
+      console.log(`Claude Desktop configuration ${hadExistingSecondBrainOS ? 'updated' : 'created'} at: ${claudeConfigFile}`);
+
       // Show summary of configured servers
       const serverCount = Object.keys(existingConfig.mcpServers).length;
       console.log(`\nTotal MCP servers configured: ${serverCount}`);
       console.log('Configured servers:', Object.keys(existingConfig.mcpServers).join(', '));
-      
+
     } catch (error) {
       console.error('Error writing configuration file:', error);
       process.exit(1);
     }
-    
+
+    // Configure Claude Code
+    const cliPath = path.join(packageRoot, 'bin', 'cli.js');
+    const claudeCodeConfigured = await configureClaudeCode(cliPath, nodePath);
+
     console.log('\nInstallation successful!');
-    console.log('\nPlease follow these steps to complete setup:');
+    console.log('\nClaude Desktop:');
     console.log('1. Completely quit Claude Desktop if it is running');
     console.log('2. Restart Claude Desktop');
     console.log('3. In the Chat Input inside Claude (i.e where you type your messages), you will now see a "🔨" icon which contains all the tools you have access to');
+    if (claudeCodeConfigured) {
+      console.log('\nClaude Code:');
+      console.log('1. Restart Claude Code if it is running');
+      console.log('2. Your Second Brain OS tools will be available automatically');
+    }
     console.log('\nIf you encounter issues, check the logs:');
     console.log(`${getLogPath()}`);
-    
+
   } catch (error) {
     console.error('Unexpected error:', error);
     process.exit(1);

package/package.json

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