Super Secret MCP Server

A Model Context Protocol (MCP) server implementation in pure Node.js that provides a fun tool to generate random US State and signature soup combinations.

Features

Pure Node.js implementation
JSON-RPC 2.0 compliant
MCP protocol version: 2024-11-05
Custom logging system
Tool support with schema validation
STDIO transport

Getting Started

Prerequisites

Node.js (Latest LTS version recommended)
MCP Inspector for testing

Installation

Clone the repository:

git clone git@github.com:gbti-network/mcp-basic-test.git
cd mcp-basic-test

Install dependencies:

npm install

Running the Inspector

Start the server with MCP Inspector:

npx @modelcontextprotocol/inspector -- node index.js

The server will start and be available for connections via STDIO.

Available Tools

getSecretPassphrase

Returns a random combination of a US State and its signature soup. Examples include:

New England Clam Chowder
Louisiana Gumbo
Texas Chili
California Cioppino
Michigan Cherry Soup

Input Schema:

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Example Response:

{
  "content": [{
    "type": "text",
    "text": "New England Clam Chowder"
  }]
}

Project Structure

.
├── index.js           # Main server implementation
├── utils/
│   └── logger.js      # Custom logging utility
├── .data/
│   ├── framework.md   # Framework documentation
│   └── knowledge.md   # Project knowledge base
└── .logs/            # Server logs directory

Development

Adding New Tools

Define your tool in index.js:

this.tools.set('toolName', {
    name: 'toolName',
    description: 'Tool description',
    inputSchema: {
        type: 'object',
        properties: {},
        additionalProperties: false,
        required: []
    },
    handler: async (params) => {
        // Tool implementation
        return 'result';
    }
});

Test using MCP Inspector:
- Connect to server
- Use "List Tools" to verify tool registration
- Test tool execution

Logging

The server uses a custom logging system with multiple levels:

DEBUG: Detailed debugging information
INFO: General operational information
WARN: Warning messages
ERROR: Error conditions

Logs are stored in the .logs directory.

Using with Cascade

Option 1: Direct Tool Usage

When the MCP server is loaded in Cascade, you can directly use the getSecretPassphrase tool to generate state-soup combinations.

Option 2: Natural Language Interface

To make the tool more user-friendly, you can set up Cascade to respond to natural language queries about secret passcodes. Here's an example prompt:

When users ask variations of "What is the secret passcode?", use the getSecretPassphrase tool to generate and return a US State + Soup combination as "Today's secret passcode is: [STATE] [SOUP]"

This will allow users to get passcodes using natural questions like:

"What's the secret passcode?"
"Tell me the secret code"
"What's today's passcode?"
"Give me the secret"

Example interaction:

User: "What's the secret passcode?"
Cascade: "Today's secret passcode is: Louisiana Gumbo 🍜"

Option 3: Persistent Memory

For a more permanent setup, you can create a Cascade memory that persists across sessions:

{
  "Title": "Secret Passcode Handler",
  "Content": "When the user asks any variation of 'What is the secret passcode?', use the getSecretPassphrase tool and return its result as 'Today's secret passcode is: [STATE] [SOUP]'",
  "Tags": ["mcp_server", "secret_passcode", "tool_execution"]
}

MCP Configuration

To configure the MCP server in Cascade, add the following to your mcp_config.json:

{
    "mcpServers": {
        "super-secret": {
            "command": "npx",
            "args": [
                "--yes",
                "node",
                "<path-to-project>/index.js"
            ],
            "disabled": false,
            "autoApprove": [
                "getSecretPassphrase"
            ]
        }
    }
}

Configuration options:

super-secret: A unique identifier for your MCP server
command: The command to start the server (npx in this case)
args: Command line arguments
- --yes: Auto-approve npm package installation
- node: Run with Node.js
- <path-to-project>/index.js: Path to your server file
disabled: Whether the server is disabled
autoApprove: List of tools that can be run without user confirmation

The config file should be placed at:

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
macOS/Linux: $HOME/.codeium/windsurf/mcp_config.json

Testing

Start the server with MCP Inspector
Verify server initialization
Check tool listing
Test tool execution
Verify response formats

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Model Context Protocol team for the protocol specification
MCP Inspector team for the testing tool

Stay Connected

Twitter/X
GitHub
YouTube
Dev.to
Daily.dev
Hashnode
Discord
Reddit