Second Brain OS MCP Server

This package provides a Model Context Protocol (MCP) server for integrating Second Brain OS with Claude Desktop.

Prerequisites

• Node.js v16 or higher
• Claude Desktop application
• A valid Second Brain OS account with the Claude MCP feature enabled

Installation

npm install -g secondbrainos-mcp-server

Usage

After installation, run the setup command with your USER_ID and USER_SECRET:

secondbrainos-mcp USER_ID USER_SECRET

This will:

1. Verify your account credentials
2. Confirm you have access to the Claude MCP feature
3. Create the necessary configuration files for Claude Desktop
4. Configure the server to dynamically fetch your available API endpoints

Features

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

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

Prompts (Workflows)

The server exposes your Second Brain OS workflows as MCP prompts, making them available in Claude Desktop's attach menu:

• 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
• Supports an optional user_input argument to provide additional context

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:

git clone https://github.com/your-username/secondbrainos-mcp-server.git
cd secondbrainos-mcp-server

2. Install dependencies:

npm install

3. Create a .env file from the example:

cp .env.example .env
# Edit .env with your actual USER_ID and USER_SECRET

Testing the Schema Conversion

To see how your OpenAPI schema is converted to MCP tools:

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

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. MCP Prompts: If the runPromptChain service is available, your workflows 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
3. Review the logs at the platform-specific location mentioned during setup

Authentication errors

• Verify your USER_ID and USER_SECRET are correct
• 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

License

MIT