secondbrainos-mcp-server 1.7.0 → 1.8.0

package/README.md

@@ -56,6 +56,7 @@ The server exposes four types of MCP prompts, available as slash commands (e.g.
 
 #### 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
+- This is the **zero-cost discovery mechanism** — Claude can read this prompt to learn what agents and skills are available without calling `getAIAgentsSchema` or `runPromptChain` as MCP tools (which would be billed). All discovery data comes from the in-memory cache populated at session init
 - Useful for orienting Claude at the start of a session
 
 #### Skills (Workflows)
@@ -142,20 +143,38 @@ Credentials are stored securely at `~/.secondbrainos/credentials.json` (created
 
 ## How It Works
 
-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**: 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
+### 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
+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
+   - `generateFileUploadGoogleCloudStorageURL` — used only when a tool argument contains a local file path
+3. **MCP server connects** via stdio — no API calls yet, no credits spent
+
+### Cache Population (on first connection)
+
+4. **ListPrompts trigger**: Claude Code automatically calls `ListPrompts` on connect. This is when the first credits are spent:
+   - `runPromptChain` is called with `{}` → returns all user workflows with prompt metadata (name, order, description)
+   - `getAIAgentsSchema` is called with `{include_sensitive_config: false}` → 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`
+
+### During the Session
+
+7. **Slash commands** (0 credits): When a user runs a slash command (e.g. `/secondbrainos:agent_my_agent`), the server returns the full agent/skill definition from cache — no API calls
+8. **`start_secondbrainos`** (0 credits): Builds a context document from cached agents and workflows — an index of all available slash commands with descriptions, enabling Claude to discover and invoke agents/skills autonomously
+9. **Tool calls** (billed per call): When Claude calls an MCP tool (e.g. `runPromptChain` with a specific entity/entity_id to fetch prompt instructions, or `searchMyKnowledge`), the server executes the API call via `api.secondbrainos.com` with authentication
+10. **File upload**: If a tool argument contains a local file path (e.g. `addToMyKnowledge` with `file_path`), the server validates the extension, uploads the file to GCS via `generateFileUploadGoogleCloudStorageURL`, and replaces the path with the GCS URI before forwarding the API call
 
 ### Credit Cost
 
 | Event | Credits |
 |-------|---------|
-| Session init | n workflows + n agents |
+| Schema fetch | 0 |
+| Session init (ListPrompts) | n workflows + n agents |
 | Slash commands | 0 (cached) |
+| `start_secondbrainos` | 0 (cached) |
 | Tool calls | Billed per call via service router |
 
 See [`docs/architecture.md`](docs/architecture.md) for detailed diagrams.

package/bin/cli.js

@@ -358,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

@@ -444,7 +444,7 @@ class SecondBrainOSServer {
         }
         const url = `${this.baseUrl}${this.getAIAgentsSchemaPath}`;
         const response = await axios.post(url, {
-            include_sensitive_config: true
+            include_sensitive_config: false
         }, {
             headers: {
                 'Authorization': `Bearer ${this.userId}:${this.userSecret}`,
@@ -614,13 +614,18 @@ An agent definition combines:
 3. **Workflows (Skills)** — the prompt chains the agent follows
 
 ## 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
+- To get full agent definitions (behaviour, knowledge, actions, workflows): use the \`getAIAgentsSchema\` tool with \`tab_id\` to fetch a specific agent — never call without \`tab_id\`
+- To get full skill/workflow details and run prompt chains: use the \`runPromptChain\` tool with \`entity\` and \`entity_id\` to fetch a specific workflow or prompt — never call without both parameters
 
 ## Accessing Agents & Skills
 - **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
 
+## Copyright
+- Never reproduce copyrighted content verbatim — summarise, paraphrase, or cite instead
+- When referencing copyrighted material from knowledge bases or external sources, always attribute the source
+- If a user requests full reproduction of copyrighted text, decline and offer a summary
+
 ## Available Agents
 ${agentIndex || '_None configured_'}
 

package/package.json

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