mcp-search-package

A drop-in replacement for mcp-remote that adds safe file management capabilities while preserving all existing mcp-remote functionality.

What is this?

This package extends mcp-remote by adding direct file manipulation capabilities for mcp.json configuration files. It:

• Acts as a complete drop-in replacement for mcp-remote
• Passes through all standard mcp-remote functionality unchanged
• Adds safe file management operations on top

Usage

Instead of:

{
  "mcpServers": {
    "mcp-search-tool": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcpsearchtool.com/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

Simply change mcp-remote to mcp-search-package:

{
  "mcpServers": {
    "mcp-search-tool": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-search-package",
        "https://mcpsearchtool.com/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

All existing mcp-remote arguments and features continue to work exactly the same. The package internally uses mcp-remote for all standard MCP operations.

Added Features

On top of standard mcp-remote functionality, this package adds:

• Safe file operations for mcp.json
• Automatic backup/restore
• Concurrent access handling
• Permission preservation
• Streamable HTTP features with HTTP polling to support cloudflare rust workers
• MCP Protocol Compliance: Proper schema validation for tools/list responses using the official MCP SDK
• Enhanced Tool Discovery: Validates tool responses against ListToolsResultSchema
• Improved Error Handling: Better error reporting for MCP protocol violations
• OAuth 2.0 Authentication (PKCE): Built-in browser-based OAuth flow with dynamic client registration and optional token refresh

How it Works

1. All standard MCP requests are passed through to mcp-remote
2. File management requests are handled by our additional layer
3. File operations use atomic writes with backup/restore
4. Concurrent access is handled safely
5. MCP Protocol Validation: All tools/list responses are validated against official MCP schemas
6. Enhanced Discovery: Tool discovery follows the Model Context Protocol specification exactly

Requirements

Same as mcp-remote, plus:

• Node.js 14+
• Write permissions for mcp.json location

Why This Tool?

Different MCP clients store their configurations in different locations:

• Cursor: ~/.cursor/mcp.json
• Claude Desktop:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

This tool helps you:

1. Manage configurations across all these locations
2. Safely add/remove/update MCP server configurations
3. Handle different transport strategies and authentication methods
4. Apply best practices for each client

Installation

npm install -g mcp-search-package

Usage

Add a New Server

# Basic usage with /mcp endpoint (HTTP transport)
mcp-search-package add <server-name> \
  --args mcp-search-package https://mcpsearchtool.com/mcp


# With transport strategy
mcp-search-package add <server-name> \
  --args mcp-search-package https://mcpsearchtool.com/mcp --transport http-only

# With OAuth client info
mcp-search-package add <server-name> \
  --args mcp-search-package https://mcpsearchtool.com/mcp \
  --static-oauth-client-info @/path/to/oauth.json

# With custom headers (avoiding spaces)
mcp-search-package add <server-name> \
  --args mcp-search-package https://mcpsearchtool.com/mcp \
  --header Authorization:${AUTH_HEADER} \
  --env AUTH_HEADER="Bearer your-token"

# With debug mode
mcp-search-package add <server-name> \
  --command npx \
  --args mcp-search-package https://mcpsearchtool.com/mcp --transport http-only \
  --env KEY=value

Common Configuration Templates

# Basic HTTP server using /mcp endpoint
mcp-search-package add http-server \
  --args "-y" "mcp-search-package" "https://mcpsearchtool.com/mcp" "--transport" "http-only"

# Debug mode with custom port
mcp-search-package add debug-server \
  --args "mcp-search-package" "https://debug.mcpsearchtool.com/mcp" "9696" "--debug"

Transport Strategies

The tool supports HTTP transport strategies:

• http-only: Uses HTTP transport (/mcp endpoint)

Authentication (OAuth 2.0)

This package now supports OAuth-protected MCP servers. When a server requires authentication, the CLI:

• Opens your browser to the authorization page (PKCE flow, no client secret)
• Starts a local callback server and listens on an approved port
• Completes the code exchange and connects automatically

Quick start

# Connect to an OAuth-protected MCP endpoint
mcp-search-package https://mcpsearchtool.com/mcp

# Optional: specify a callback port (must be approved)
mcp-search-package https://mcpsearchtool.com/mcp --port 8787

CLI flags

• --no-auth: Skip authentication (testing only)
• --mcp-endpoint <path>: Override detected MCP endpoint (e.g. /mcp, /cursor, /sse, /dev)
• --port <number>: Choose a callback port. Approved values: 8787, 8081, 52172

Token Management

The CLI includes commands for managing stored OAuth tokens:

# List stored tokens for a server
mcp-search-package tokens list [server-url]

# Check token status and expiration
mcp-search-package tokens status [server-url]

# Clear all stored tokens for a server
mcp-search-package tokens clear [server-url]

Security Features:

• Tokens are encrypted using AES-256-GCM with unique per-server keys
• Files are stored with restrictive permissions (600)
• Automatic token expiration handling
• Secure key storage in ~/.mcp-file-manager/

Behavior and storage

• Uses PKCE and dynamic client registration when supported by the server
• Honors RFC 8414/9728 discovery if the server exposes well-known metadata
• Secure Token Persistence: Tokens are encrypted and stored securely on disk for future sessions
• Automatic Token Refresh: Handles token expiration and refresh automatically
• Cross-Session Persistence: Tokens persist between CLI sessions and application restarts

See the detailed guide: OAuth-Protected MCP Client Implementation Guide

List All Servers

mcp-search-package list

Update a Server

# Update to use HTTP endpoint
mcp-search-package update <server-name> \
  --args mcp-search-package https://new-url.com/mcp --transport http-only

Remove a Server

mcp-search-package remove <server-name>

Configuration File Locations

The tool automatically manages configurations in the correct locations for each MCP client:

• Cursor: ~/.cursor/mcp.json
• Claude Desktop:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Features

• ✅ Multi-client support (Cursor, Claude Desktop, Windsurf)
• ✅ Support for /mcp endpoint
• ✅ Transport strategy management (http-only)
• ✅ OAuth configuration handling
• ✅ Custom headers and environment variables
• ✅ Debug mode support
• ✅ Automatic client detection and configuration
• ✅ Safe file manipulation with backups

Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run in development mode:

   npm run dev

Project Structure

mcp-search-package/
├── src/
│   ├── cli.ts           # Command-line interface
│   ├── fileManager.ts   # Core file manipulation
│   ├── clients/         # Client-specific handlers
│   │   ├── cursor.ts    # Cursor config handler
│   │   ├── claude.ts    # Claude Desktop handler
│   │   └── windsurf.ts  # Windsurf config handler
│   └── utils/           # Utility functions
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

Common Issues

1. Authentication Errors:

   • Clear ~/.mcp-auth directory
   • Restart your MCP client
   • Check OAuth configuration

2. VPN Issues:

   • Set NODE_EXTRA_CA_CERTS in your configuration
   • Use the --allow-http flag in trusted networks

3. Client Not Updating:

   • Restart the MCP client after configuration changes
   • Check client-specific logs
   • Enable debug mode with --debug flag

4. Endpoint Issues:

   • Ensure you're using the /mcp endpoint
   • Verify the server supports HTTP transport

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

ISC