secondbrainos-mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -28,25 +28,122 @@ This will:
 3. Create the necessary configuration files for Claude Desktop
 4. Configure the server to dynamically fetch your available API endpoints
 
-### After Installation
+## Features
 
-1. Completely quit Claude Desktop if it is running
-2. Restart Claude Desktop
-3. Look for the Second Brain OS server in the 🔌 plugins menu
+### Enhanced OpenAPI Support
+The server uses `@samchon/openapi` library for robust OpenAPI handling, providing:
+- Support for all OpenAPI/Swagger versions (v2.0, v3.0, v3.1)
+- Automatic schema conversion to a standardized format
+- Better handling of complex schemas including references, nullable properties, and union types
 
-## Troubleshooting
+### Improved Function Execution
+- Type-safe function execution with built-in error handling
+- Automatic request formatting based on OpenAPI specifications
+- Support for complex parameters and nested objects
+
+### Better Error Handling
+- Detailed error messages for debugging
+- Proper handling of authentication failures, bad requests, and service errors
+- Graceful fallback for unexpected errors
+
+## Development
+
+### Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/your-username/secondbrainos-mcp-server.git
+cd secondbrainos-mcp-server
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Create a `.env` file from the example:
+```bash
+cp .env.example .env
+# Edit .env with your actual USER_ID and USER_SECRET
+```
+
+### Testing the Schema Conversion
 
-If you encounter issues, check the Claude Desktop logs:
+To see how your OpenAPI schema is converted to MCP tools:
 
 ```bash
-tail -f ~/Library/Logs/Claude/mcp*.log
+npm run test-conversion
+```
+
+This will:
+- Fetch your OpenAPI schema from Second Brain OS
+- Convert it to LLM function calling format
+- Display all available functions and their schemas
+- Show any conversion errors
+- Demonstrate the MCP tool format
+
+### Development Scripts
+
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm run dev` - Run the MCP server in development mode
+- `npm run test-conversion` - Test the OpenAPI to MCP conversion
+- `npm start` - Run the compiled server
+
+### Project Structure
+
+```
+secondbrainos-mcp-server/
+├── src/
+│   ├── index.ts           # Main MCP server implementation
+│   └── test-conversion.ts # Schema conversion testing utility
+├── build/                 # Compiled JavaScript (git-ignored)
+├── bin/
+│   └── cli.js            # CLI setup script
+├── .env.example          # Environment variables template
+├── package.json          # Package configuration
+├── tsconfig.json         # TypeScript configuration
+└── README.md            # This file
 ```
 
-Common issues:
-- Make sure Node.js is properly installed
+## Environment Variables
+
+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
+
+## How It Works
+
+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. **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
+3. Review the logs at the platform-specific location mentioned during setup
+
+### Authentication errors
 - Verify your USER_ID and USER_SECRET are correct
-- Ensure you have the Claude MCP feature enabled in your account
+- Ensure your account has the Claude MCP feature enabled
+- Check that your credentials haven't expired
+
+### Schema conversion errors
+- Run `npm run test-conversion` to see detailed error messages
+- Some complex OpenAPI features may not be supported by LLM function calling
+- Check the console output for specific endpoints that failed conversion
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-## Support
+## License
 
-If you continue to experience problems, please contact support at support@secondbrainos.com
+MIT

package/build/index.js

@@ -1,20 +1,35 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListResourcesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, CallToolRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { OpenApi, HttpLlm } from "@samchon/openapi";
 import axios from "axios";
 import dotenv from "dotenv";
 import yaml from 'js-yaml';
 dotenv.config();
 class SecondBrainOSServer {
     constructor(initialSchema) {
-        // Initialize with provided schema instead of URL
-        this.apiSpec = initialSchema;
+        this.originalSpec = initialSchema;
         this.baseUrl = process.env.API_BASE_URL || 'https://api.secondbrainos.com';
         this.userId = process.env.USER_ID || '';
         this.userSecret = process.env.USER_SECRET || '';
         if (!this.userId || !this.userSecret) {
             throw new Error("USER_ID and USER_SECRET environment variables are required");
         }
+        // Convert OpenAPI schema using @samchon/openapi
+        const document = OpenApi.convert(initialSchema);
+        // Create LLM application with proper model configuration
+        this.application = HttpLlm.application({
+            model: "chatgpt",
+            document
+        });
+        // Create a map of operationId to function for easier lookup
+        this.functionMap = new Map();
+        this.application.functions.forEach(func => {
+            const operation = func.operation();
+            if (operation.operationId) {
+                this.functionMap.set(operation.operationId, func);
+            }
+        });
         this.server = new Server({
             name: "secondbrainos-server",
             version: "1.0.0"
@@ -27,24 +42,6 @@ class SecondBrainOSServer {
         this.setupHandlers();
         this.setupErrorHandling();
     }
-    // Helper method to extract functions from the API spec
-    getFunctions() {
-        const functions = [];
-        for (const [path, pathItem] of Object.entries(this.apiSpec.paths)) {
-            for (const [method, operation] of Object.entries(pathItem)) {
-                if (operation.operationId) {
-                    functions.push({
-                        operationId: operation.operationId,
-                        path,
-                        method: method.toUpperCase(),
-                        summary: operation.summary || operation.operationId,
-                        schema: operation.requestBody?.content?.['application/json']?.schema || {}
-                    });
-                }
-            }
-        }
-        return functions;
-    }
     setupHandlers() {
         // List available resources
         this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
@@ -53,7 +50,7 @@ class SecondBrainOSServer {
                         uri: 'secondbrainos://api/spec',
                         name: 'Second Brain OS API Specification',
                         mimeType: 'application/yaml',
-                        description: this.apiSpec?.info?.title || 'API Specification'
+                        description: this.originalSpec?.info?.title || 'API Specification'
                     }]
             };
         });
@@ -66,47 +63,67 @@ class SecondBrainOSServer {
                 contents: [{
                         uri: request.params.uri,
                         mimeType: 'application/yaml',
-                        text: yaml.dump(this.apiSpec)
+                        text: yaml.dump(this.originalSpec)
                     }]
             };
         });
-        // List available tools
+        // List available tools - now using operationId as the tool name
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            const functions = this.getFunctions();
-            return {
-                tools: functions.map(func => ({
-                    name: func.operationId,
-                    description: func.summary,
-                    inputSchema: func.schema
-                }))
-            };
+            const tools = [];
+            // Iterate through the function map to get tools with proper names
+            for (const [operationId, func] of this.functionMap) {
+                tools.push({
+                    name: operationId,
+                    description: func.description || operationId,
+                    inputSchema: func.parameters // Convert to MCP format
+                });
+            }
+            // Also include functions without operationId (fallback)
+            this.application.functions.forEach(func => {
+                const operation = func.operation();
+                if (!operation.operationId) {
+                    tools.push({
+                        name: func.name,
+                        description: func.description || func.name,
+                        inputSchema: func.parameters
+                    });
+                }
+            });
+            return { tools };
         });
-        // Handle tool calls
+        // Handle tool calls - now supporting both operationId and original names
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            const functions = this.getFunctions();
-            const func = functions.find(f => f.operationId === request.params.name);
+            // First try to find by operationId
+            let func = this.functionMap.get(request.params.name);
+            // If not found, try the original function name
+            if (!func) {
+                func = this.application.functions.find(f => f.name === request.params.name);
+            }
             if (!func) {
                 throw new McpError(ErrorCode.MethodNotFound, `Unknown function: ${request.params.name}`);
             }
             try {
-                const bearerToken = `${this.userId}:${this.userSecret}`;
-                const response = await axios({
-                    method: func.method,
-                    url: `${this.baseUrl}${func.path}`,
-                    data: request.params.arguments,
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'Authorization': `Bearer ${bearerToken}`
-                    }
+                // Use HttpLlm.execute for better error handling and type safety
+                const result = await HttpLlm.execute({
+                    connection: {
+                        host: this.baseUrl,
+                        headers: {
+                            'Authorization': `Bearer ${this.userId}:${this.userSecret}`
+                        }
+                    },
+                    application: this.application, // Type assertion to avoid generic issues
+                    function: func,
+                    input: request.params.arguments || {}
                 });
                 return {
                     content: [{
                             type: 'text',
-                            text: JSON.stringify(response.data, null, 2)
+                            text: JSON.stringify(result, null, 2)
                         }]
                 };
             }
             catch (error) {
+                // Better error handling with HttpLlm
                 if (axios.isAxiosError(error)) {
                     const status = error.response?.status;
                     const errorMessage = error.response?.data?.error || error.message;
@@ -135,12 +152,21 @@ class SecondBrainOSServer {
                         isError: true
                     };
                 }
+                else if (error instanceof Error) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Error calling function: ${error.message}`
+                            }],
+                        isError: true
+                    };
+                }
                 throw error;
             }
         });
     }
     setupErrorHandling() {
-        // Add any error handling setup here
+        // Error handling is now built into HttpLlm.execute
         // This method is kept for future error handling implementations
     }
     async run() {

package/build/test-mcp-conversion.js

@@ -0,0 +1,135 @@
+import { OpenApi, HttpLlm } from "@samchon/openapi";
+import axios from "axios";
+import dotenv from "dotenv";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+// Get __dirname equivalent for ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Load environment variables
+dotenv.config();
+// Function to fetch the schema from the API
+async function fetchSchema() {
+    const userId = process.env.USER_ID;
+    if (!userId) {
+        throw new Error("USER_ID environment variable is required");
+    }
+    console.log("Fetching schema for user:", userId);
+    try {
+        const response = await axios.post('https://us-central1-second-brain-os.cloudfunctions.net/generate-open-api-schema', { user_id: userId }, {
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+        return response.data;
+    }
+    catch (error) {
+        console.error('Failed to fetch schema:', error);
+        throw new Error('Failed to fetch API schema');
+    }
+}
+async function testMCPConversion() {
+    try {
+        console.log("=== MCP Conversion Test ===\n");
+        // Step 1: Fetch the original schema
+        console.log("1. Fetching OpenAPI schema...");
+        const originalSchema = await fetchSchema();
+        console.log("✓ Schema fetched successfully");
+        console.log(`  - Title: ${originalSchema.info?.title}`);
+        console.log(`  - Version: ${originalSchema.info?.version}`);
+        console.log(`  - Number of paths: ${Object.keys(originalSchema.paths || {}).length}\n`);
+        // Save original schema for reference
+        await fs.writeFile(path.join(__dirname, '../output/original-schema.json'), JSON.stringify(originalSchema, null, 2));
+        console.log("✓ Original schema saved to output/original-schema.json\n");
+        // Step 2: Convert using OpenApi
+        console.log("2. Converting schema using @samchon/openapi...");
+        const document = OpenApi.convert(originalSchema);
+        console.log("✓ Schema converted to OpenApi format\n");
+        // Step 3: Create LLM application
+        console.log("3. Creating LLM application...");
+        const application = HttpLlm.application({
+            model: "chatgpt",
+            document
+        });
+        console.log("✓ LLM application created");
+        console.log(`  - Number of functions: ${application.functions.length}\n`);
+        // Step 4: Create MCP-compatible tools
+        console.log("4. Converting to MCP tool format...");
+        const mcpTools = [];
+        const functionMap = new Map();
+        application.functions.forEach(func => {
+            const operation = func.operation();
+            const operationId = operation.operationId || func.name;
+            functionMap.set(operationId, func);
+            const mcpTool = {
+                name: operationId,
+                description: func.description || operationId,
+                inputSchema: func.parameters
+            };
+            mcpTools.push(mcpTool);
+        });
+        console.log(`✓ Converted ${mcpTools.length} tools to MCP format\n`);
+        // Step 5: Save the results
+        console.log("5. Saving conversion results...");
+        // Create output directory if it doesn't exist
+        await fs.mkdir(path.join(__dirname, '../output'), { recursive: true });
+        // Save MCP tools
+        await fs.writeFile(path.join(__dirname, '../output/mcp-tools.json'), JSON.stringify(mcpTools, null, 2));
+        console.log("✓ MCP tools saved to output/mcp-tools.json");
+        // Save function details
+        const functionDetails = application.functions.map(func => {
+            const operation = func.operation();
+            // Extract method and path from the route property if available
+            let method;
+            let path;
+            // The operation might have these properties in different ways depending on the OpenAPI version
+            // Let's check the actual structure
+            const route = operation.route;
+            if (route) {
+                method = route.method;
+                path = route.path;
+            }
+            return {
+                name: func.name,
+                operationId: operation.operationId,
+                method,
+                path,
+                description: func.description,
+                parameters: func.parameters,
+                operation: {
+                    summary: operation.summary,
+                    description: operation.description,
+                    tags: operation.tags
+                }
+            };
+        });
+        await fs.writeFile(path.join(__dirname, '../output/function-details.json'), JSON.stringify(functionDetails, null, 2));
+        console.log("✓ Function details saved to output/function-details.json\n");
+        // Step 6: Display summary
+        console.log("=== Conversion Summary ===");
+        console.log(`Total tools converted: ${mcpTools.length}`);
+        console.log("\nSample tools:");
+        mcpTools.slice(0, 5).forEach(tool => {
+            console.log(`  - ${tool.name}: ${tool.description}`);
+        });
+        if (mcpTools.length > 5) {
+            console.log(`  ... and ${mcpTools.length - 5} more`);
+        }
+        console.log("\n✓ Test completed successfully!");
+        console.log("\nCheck the 'output' directory for:");
+        console.log("  - original-schema.json: The raw OpenAPI schema from the API");
+        console.log("  - mcp-tools.json: Tools in MCP format");
+        console.log("  - function-details.json: Detailed function information");
+    }
+    catch (error) {
+        console.error("\n❌ Test failed:", error);
+        if (error instanceof Error) {
+            console.error("Error details:", error.message);
+        }
+        process.exit(1);
+    }
+}
+// Run the test
+testMCPConversion().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secondbrainos-mcp-server",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Second Brain OS MCP Server for Claude Desktop",
   "type": "module",
   "main": "build/index.js",
@@ -8,8 +8,17 @@
   "bin": {
     "secondbrainos-mcp": "bin/cli.js"
   },
+  "files": [
+    "build/",
+    "bin/",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node build/index.js",
+    "test-conversion": "tsx src/test-mcp-conversion.ts",
     "prepublishOnly": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
@@ -23,6 +32,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@samchon/openapi": "^2.0.0",
     "axios": "^1.8.2",
     "dotenv": "^16.4.7",
     "js-yaml": "^4.1.0"
@@ -31,6 +41,7 @@
     "@types/js-yaml": "^4.0.5",
     "@types/node": "^20.8.10",
     "ts-node": "^10.9.1",
+    "tsx": "^4.7.0",
     "typescript": "^5.2.2"
   },
   "engines": {

package/.env

@@ -1,2 +0,0 @@
-USER_ID=
-USER_SECRET=

package/gitignore.txt

@@ -1,130 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-.pnpm-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
-node_modules/
-jspm_packages/
-
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Microbundle cache
-.rpt2_cache/
-.rts2_cache_cjs/
-.rts2_cache_es/
-.rts2_cache_umd/
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
-.env
-.env.development.local
-.env.test.local
-.env.production.local
-.env.local
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp and cache directory
-.temp
-.cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# yarn v2
-.yarn/cache
-.yarn/unplugged
-.yarn/build-state.yml
-.yarn/install-state.gz
-.pnp.*