secondbrainos-mcp-server 1.0.4 → 1.0.5

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,27 @@
 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
+        });
         this.server = new Server({
             name: "secondbrainos-server",
             version: "1.0.0"
@@ -27,24 +34,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 +42,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 +55,48 @@ 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 @samchon/openapi functions
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            const functions = this.getFunctions();
             return {
-                tools: functions.map(func => ({
-                    name: func.operationId,
-                    description: func.summary,
-                    inputSchema: func.schema
+                tools: this.application.functions.map(func => ({
+                    name: func.name,
+                    description: func.description || func.name,
+                    inputSchema: func.parameters // Convert to MCP format
                 }))
             };
         });
         // Handle tool calls
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            const functions = this.getFunctions();
-            const func = functions.find(f => f.operationId === request.params.name);
+            const 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 +125,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-conversion.js

@@ -0,0 +1,81 @@
+import { OpenApi, HttpLlm } from "@samchon/openapi";
+import axios from "axios";
+import dotenv from "dotenv";
+dotenv.config();
+async function testSchemaConversion() {
+    const userId = process.env.USER_ID;
+    const userSecret = process.env.USER_SECRET;
+    if (!userId || !userSecret) {
+        console.error("❌ USER_ID and USER_SECRET environment variables are required");
+        console.error("Create a .env file with:");
+        console.error("USER_ID=your_user_id");
+        console.error("USER_SECRET=your_user_secret");
+        process.exit(1);
+    }
+    console.log("🔄 Fetching OpenAPI schema from Second Brain OS...");
+    try {
+        // Fetch the schema
+        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'
+            }
+        });
+        const openApiSchema = response.data;
+        console.log("✅ Schema fetched successfully!");
+        console.log(`📋 API Title: ${openApiSchema.info?.title || 'Unknown'}`);
+        console.log(`📋 API Version: ${openApiSchema.info?.version || 'Unknown'}`);
+        // Convert to emended OpenAPI document
+        console.log("\n🔄 Converting to emended OpenAPI format...");
+        const document = OpenApi.convert(openApiSchema);
+        console.log("✅ Conversion successful!");
+        // Create LLM application
+        console.log("\n🔄 Creating LLM function calling application...");
+        const application = HttpLlm.application({
+            model: "chatgpt",
+            document
+        });
+        console.log("✅ LLM application created!");
+        // Display the converted functions
+        console.log(`\n📊 Total functions available: ${application.functions.length}`);
+        console.log(`⚠️  Errors during conversion: ${application.errors.length}`);
+        if (application.errors.length > 0) {
+            console.log("\n❌ Conversion errors:");
+            application.errors.forEach((error, index) => {
+                console.log(`  ${index + 1}. ${error.method.toUpperCase()} ${error.path}`);
+                error.messages.forEach(msg => console.log(`     - ${msg}`));
+            });
+        }
+        console.log("\n🔧 Available MCP Tools:");
+        console.log("=".repeat(80));
+        application.functions.slice(0, 10).forEach((func, index) => {
+            console.log(`\n${index + 1}. ${func.name}`);
+            console.log(`   Method: ${func.method.toUpperCase()}`);
+            console.log(`   Path: ${func.path}`);
+            console.log(`   Description: ${func.description?.split('\n')[0] || 'No description'}`);
+            console.log(`   Parameters Schema: ${JSON.stringify(func.parameters).substring(0, 100)}...`);
+        });
+        if (application.functions.length > 10) {
+            console.log(`\n... and ${application.functions.length - 10} more functions`);
+        }
+        // Show a sample of how it would look as MCP tools
+        console.log("\n\n🎯 Sample MCP Tool Format:");
+        console.log("=".repeat(80));
+        const sampleFunc = application.functions[0];
+        if (sampleFunc) {
+            const mcpTool = {
+                name: sampleFunc.name,
+                description: sampleFunc.description || sampleFunc.name,
+                inputSchema: sampleFunc.parameters
+            };
+            console.log(JSON.stringify(mcpTool, null, 2));
+        }
+    }
+    catch (error) {
+        console.error("❌ Error:", error instanceof Error ? error.message : error);
+        if (axios.isAxiosError(error) && error.response) {
+            console.error("Response data:", error.response.data);
+        }
+    }
+}
+// Run the test
+testSchemaConversion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secondbrainos-mcp-server",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "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-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,9 +41,10 @@
     "@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": {
     "node": ">=16.0.0"
   }
-}
+}

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.*