secondbrainos-mcp-server 1.8.2 → 1.9.1

package/README.md

@@ -69,6 +69,12 @@ The server exposes four types of MCP prompts, available as slash commands (e.g.
 - 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
 
+#### Features
+- Extracted from the `features` array in the `schema.secondbrainos.com` response at startup, then cached
+- Each feature appears with a `[Feature]` prefix and returns its `guidelines` text
+- Features have consistent guidelines for all users (not user-specific)
+- 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
@@ -145,7 +151,7 @@ Credentials are stored securely at `~/.secondbrainos/credentials.json` (created
 
 ### Startup & Session Init
 
-1. **Schema Fetching** (0 credits): On startup, the server POSTs your `user_id` to `schema.secondbrainos.com` and receives your personalized OpenAPI spec
+1. **Schema Fetching** (0 credits): On startup, the server POSTs your `user_id` to `schema.secondbrainos.com` and receives your personalized OpenAPI spec along with a `features` array (consistent guidelines for all users)
 2. **Schema Conversion**: The `@samchon/openapi` library converts the spec to LLM function calling format. Each API endpoint becomes an MCP tool. Three service paths are discovered from the spec for internal use:
    - `runPromptChain` — fetches workflows/skills
    - `getAIAgentsSchema` — fetches agents
@@ -158,7 +164,7 @@ Credentials are stored securely at `~/.secondbrainos/credentials.json` (created
    - `runPromptChain` is called with `{}` → returns all user workflows with prompt metadata (name, order, description)
    - `getAIAgentsSchema` is called with `{include_sensitive_config: true}` → returns all user agents with behaviour, knowledge collection ID, actions, and workflows
 5. **In-memory cache**: Both responses are normalized (consistent field names, defaults applied) and sorted (prompts ordered by `order` field), then stored in memory as `cachedWorkflows`, `cachedAgents`, and name-to-ID lookup maps
-6. **Slash commands exposed**: The cached data is surfaced as MCP prompts — `/secondbrainos:skill_*`, `/secondbrainos:agent_*`, `/secondbrainos:start_secondbrainos`, and `/secondbrainos:knowledge_bases`
+6. **Slash commands exposed**: The cached data is surfaced as MCP prompts — `/secondbrainos:feature_*`, `/secondbrainos:skill_*`, `/secondbrainos:agent_*`, `/secondbrainos:start_secondbrainos`, and `/secondbrainos:knowledge_bases`
 
 ### During the Session
 

package/build/index.js

@@ -15,8 +15,9 @@ function toSnakeCase(str) {
         .replace(/^_+|_+$/g, '');
 }
 class SecondBrainOSServer {
-    constructor(initialSchema) {
+    constructor(initialSchema, features = []) {
         this.originalSpec = initialSchema;
+        this.cachedFeatures = features;
         this.baseUrl = process.env.API_BASE_URL || 'https://api.secondbrainos.com';
         this.userId = process.env.USER_ID || '';
         this.userSecret = process.env.USER_SECRET || '';
@@ -246,6 +247,22 @@ class SecondBrainOSServer {
                     console.error('Failed to fetch agents for prompts/list:', error);
                 }
             }
+            // Add feature prompts (from schema response, cached at startup)
+            for (const feature of this.cachedFeatures) {
+                const snakeName = `feature_${toSnakeCase(feature.name)}`;
+                prompts.push({
+                    name: snakeName,
+                    title: `[Feature] ${feature.name}`,
+                    description: feature.guidelines.slice(0, 200) || feature.name,
+                    arguments: [
+                        {
+                            name: "user_input",
+                            description: "Optional context or input",
+                            required: false
+                        }
+                    ]
+                });
+            }
             // Add start_secondbrainos prompt — returns the server-use context document
             prompts.push({
                 name: "start_secondbrainos",
@@ -333,6 +350,34 @@ class SecondBrainOSServer {
                     messages
                 };
             }
+            // Check if this is a feature prompt
+            if (promptName.startsWith('feature_')) {
+                const feature = this.cachedFeatures.find(f => `feature_${toSnakeCase(f.name)}` === promptName);
+                if (feature) {
+                    const messages = [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: feature.guidelines
+                            }
+                        }
+                    ];
+                    if (userInput) {
+                        messages.push({
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: userInput
+                            }
+                        });
+                    }
+                    return {
+                        description: `Feature: ${feature.name}`,
+                        messages
+                    };
+                }
+            }
             // Check if this is an agent prompt
             const agentId = this.agentNameToId.get(promptName);
             if (agentId) {
@@ -626,11 +671,42 @@ An agent definition combines:
 - NEVER write these to local disk/drive — even if the user asks. They must always be fetched live from Second Brain OS to avoid stale data
 - Always retrieve the latest version from the server rather than caching or saving locally
 
+## Notes on Key Tools
+
+### File Uploads (\`generateFileUploadGoogleCloudStorageURL\`)
+- **Almost never call this directly.** The MCP server uses it transparently: when any tool argument named \`file_path\` (or containing \`file_path\`) is a local file path, the server automatically uploads the file to GCS via this service and replaces the path with a \`gs://\` URI before forwarding the call.
+- Only \`.txt\` and \`.md\` files are supported. \`https://\` URLs are passed through unchanged; \`http://\` is rejected.
+
+### Discovery Tools (\`runPromptChain\`, \`getAIAgentsSchema\`)
+- Use these to **fetch a specific** workflow, prompt, or agent — always pass \`entity\` + \`entity_id\` (or \`tab_id\`). Never call without these parameters.
+- They can also be used to **list all** workflows / agents, but you shouldn't need to: the start command above already lists everything the server cached at connect time.
+- **If the list returned by these tools differs from what's in this start command**, your MCP connection is stale — ask the user to reconnect/refresh the SBOS MCP server.
+
+### Marketplace Search & Service Requests (\`searchWorkflowMarketPlace\`, \`searchServicesMarketPlace\`, \`searchTabsMarketPlace\`, \`requestNewService\`)
+- Users are non-technical. Before suggesting any external step — installing plugins, fetching code from the internet, writing Python/Bash/JavaScript, or exposing webhooks — **first search the marketplaces** for an existing tool, skill, or agent.
+- If nothing matches, use \`requestNewService\` to formally request a new capability instead of working around the gap.
+- \`requestNewService\` **always requires a \`file_path\`** — write the context to a local \`.md\` or \`.txt\` file before calling it.
+
+### Sub-Agent Testing (\`messageSubAgent\`)
+- Engages the user's **public-facing AI agent** configured at \`secondbrainos.com/dashboard > Agent Settings\`.
+- Primarily used to fine-tune and test the agent: verify behaviour, validate knowledge retrieval, confirm tool availability, and debug tool execution end-to-end.
+
+### User State Tools (\`getUserServices\`, \`getUserCredits\`)
+- \`getUserServices\` — returns services the user currently has access to. If this differs from the MCP tools available in this session, ask the user to reconnect the SBOS MCP server.
+- \`getUserCredits\` — returns the user's available SBOS credits.
+
 ## Available Agents
 ${agentIndex || '_None configured_'}
 
 ## Available Skills
 ${skillIndex || '_None configured_'}
+
+## Available Features
+${this.cachedFeatures.length > 0
+            ? this.cachedFeatures
+                .map(f => `- ${f.name} → \`/secondbrainos:feature_${toSnakeCase(f.name)}\``)
+                .join('\n')
+            : '_None configured_'}
 `;
     }
     setupErrorHandling() {
@@ -653,7 +729,10 @@ async function fetchSchema() {
                 'Content-Type': 'application/json'
             }
         });
-        return response.data;
+        const data = response.data;
+        // Extract features (if present) and return separately from the OpenAPI spec
+        const { features, ...schema } = data;
+        return { schema, features: Array.isArray(features) ? features : [] };
     }
     catch (error) {
         console.error('Failed to fetch schema:', error);
@@ -664,9 +743,9 @@ async function fetchSchema() {
 async function main() {
     try {
         // Fetch the schema once at startup
-        const schema = await fetchSchema();
-        // Initialize the server with the fetched schema
-        const server = new SecondBrainOSServer(schema);
+        const { schema, features } = await fetchSchema();
+        // Initialize the server with the fetched schema and features
+        const server = new SecondBrainOSServer(schema, features);
         // Start the server
         await server.run();
     }

package/package.json

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