mcp-lite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 13 Open GitHub ↗

lightweight mcp server vibe coded with Cursor

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MCP Client Tester

A generic MCP (Model Context Protocol) client tool designed to help developers and security professionals test MCP servers for vulnerabilities. This tool can connect to MCP servers, list available tools, and provide information about server configurations.

## Features

- 🔌 Connect to MCP servers via configuration file
- 📋 List all available tools from MCP servers
- 🔧 Call and execute tools on MCP servers
- 🔍 Get detailed server information
- 🛡️ Security-focused design for vulnerability testing
- 📊 JSON output support for automation
- 🔄 Support for multiple transport types (stdio, SSE, HTTP/HTTPS)

## Installation

### Install Globally (Recommended)

```bash
npm install -g mcp-client-tester
```

After installation, the `mcp-client` command will be available globally:

```bash
mcp-client list
mcp-client servers
mcp-client info <server-name>
mcp-client call <server-name> <tool-name>
```

### Install Locally for Development

```bash
git clone <repository-url>
cd cursor-mcp-client
npm install
```

Then use via npm scripts or run directly:

```bash
# Via npm scripts
npm start -- list

# Or run directly
node src/cli.js list
```

### Requirements

- Node.js >= 18.0.0
- npm >= 9.0.0

## Configuration

Create an `MCPserver.json` file in your project root (or specify a custom path using the `--config` option). The configuration format follows the MCP standard:

```json
{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    },
    "sse-server": {
      "transport": "sse",
      "url": "http://localhost:3000/sse"
    },
    "http-server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "apiKey": "your-api-key-here"
    },
    "http-server-with-headers": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "http": {
        "headers": {
          "Authorization": "Bearer your-token-here",
          "X-Custom-Header": "value"
        }
      }
    },
    "oauth-server": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "redirectUrl": "http://localhost:8080/callback",
        "tokenEndpointAuthMethod": "client_secret_basic",
        "grantTypes": ["authorization_code"],
        "responseTypes": ["code"]
      }
    }
  }
}
```

### Configuration Options

- **command**: The command to run the server (e.g., "node", "npx", "python")
- **args**: Array of arguments to pass to the command
- **env**: Environment variables to set for the server process
- **transport**: Transport type ("stdio" default, "sse" for Server-Sent Events, "http" or "https" for HTTP/HTTPS)
- **url**: URL for SSE or HTTP transports
- **apiKey**: API key for HTTP transport (will be added as `Authorization: Bearer <apiKey>` header)
- **http**: HTTP-specific configuration object:
  - **headers**: Custom HTTP headers to include in requests
- **oauth**: OAuth 2.0 configuration object (for HTTP/HTTPS transports):
  - **clientId**: OAuth client ID
  - **clientSecret**: OAuth client secret
  - **redirectUrl**: OAuth redirect URL (must match server configuration)
  - **tokenEndpointAuthMethod**: Authentication method (default: "client_secret_basic")
  - **grantTypes**: OAuth grant types (default: ["authorization_code"])
  - **responseTypes**: OAuth response types (default: ["code"])
  - **tokenFile**: Optional path to store tokens (default: `.mcp-tokens/<server-name>.json`)

## Usage

### List all tools from all servers

```bash
# Using npm (note: use -- to pass flags through npm)
npm start -- list
# or run directly
node src/cli.js list
```

### List tools from a specific server

```bash
npm start -- list --server example-server
# or
node src/cli.js list --server example-server
```

### List all configured servers

```bash
npm start -- servers
# or
node src/cli.js servers
```

### Get server information

```bash
npm start -- info example-server
# or
node src/cli.js info example-server
```

### OAuth Authorization

For servers that require OAuth authentication:

```bash
# Attempt to connect (will show authorization URL if needed)
mcp-client list --server oauth-server

# Complete authorization with the code from the callback URL
mcp-client auth oauth-server --code <authorization-code>
# or
node src/cli.js auth oauth-server --code <authorization-code>
```

**OAuth Flow:**
1. Configure OAuth settings in your `MCPserver.json`
2. Try to connect to the server (e.g., `mcp-client list --server oauth-server`)
3. The tool will display an authorization URL
4. Open the URL in your browser and complete authorization
5. Copy the authorization code from the callback URL
6. Run `mcp-client auth <server-name> --code <code>` to complete the flow
7. Tokens are automatically saved and refreshed as needed

### Generate tool call template

Generate a template command and example arguments for calling a tool:

```bash
# Generate JSON template with example arguments
npm start -- generate example-server tool-name
# or
node src/cli.js generate example-server tool-name

# Generate as a ready-to-use command
npm start -- generate example-server tool-name --command
# or
node src/cli.js generate example-server tool-name --command

# Generate and save arguments to a file
npm start -- generate example-server tool-name --file
# or
node src/cli.js generate example-server tool-name --file
```

This command will:
- Show the tool's description and parameters
- Generate example arguments based on the tool's input schema
- Provide a ready-to-use command or JSON template

### Call a tool

Execute a tool on an MCP server. You can pass arguments as a JSON string or from a file:

```bash
# Call a tool with inline JSON arguments
npm start -- call example-server tool-name --args '{"param1":"value1","param2":"value2"}'
# or
node src/cli.js call example-server tool-name --args '{"param1":"value1","param2":"value2"}'

# Call a tool with arguments from a file
npm start -- call example-server tool-name --args-file ./args.json
# or
node src/cli.js call example-server tool-name --args-file ./args.json

# Call a tool without arguments
npm start -- call example-server tool-name
# or
node src/cli.js call example-server tool-name
```

**Example arguments file (`args.json`):**
```json
{
  "account_id": "123",
  "limit": 10,
  "include_body": true
}
```

**Tip:** Use `generate` first to create a template, then modify it and use it with `call`!

### JSON output

Add the `--json` flag to any command for machine-readable output:

```bash
npm start -- list --json
npm start -- list --server example-server --json
# or
node src/cli.js list --json
```

### Custom configuration file

You can specify a custom configuration file path using the `--config` option. The path can be absolute or relative to the current working directory:

```bash
# Using npm - IMPORTANT: Use -- to pass flags through npm
npm start -- list --config ./configs/my-servers.json
npm start -- list --config /Users/username/configs/MCPserver.json

# Running directly (no -- needed)
node src/cli.js list --config ./configs/my-servers.json
node src/cli.js list --config /Users/username/configs/MCPserver.json

# Paths with spaces MUST be quoted
node src/cli.js list --config "/Users/username/Application Support/config.json"
node src/cli.js list --config '/Users/username/Application Support/config.json'

# The config option is global, so it works with all commands
npm start -- servers --config /path/to/config.json
npm start -- info example-server --config /path/to/config.json
```

**Important:** 
- When using `npm start`, you must use `--` before your flags to pass them through to the script. For example:
  - ✅ `npm start -- list --config /path/to/config.json`
  - ❌ `npm start list --config /path/to/config.json` (npm will intercept the flag)
- **Paths with spaces must be quoted** with single or double quotes:
  - ✅ `--config "/path/with spaces/config.json"`
  - ❌ `--config /path/with spaces/config.json` (will be split at the space)

**Note:** The `--config` option is global and applies to all commands. If not specified, it defaults to `MCPserver.json` in the current working directory.

## Examples

### Basic usage

```bash
# List all tools
npm start -- list
# or
node src/cli.js list

# Output:
# 📋 Server: example-server
#    Status: ✅ Connected
#    Tools: 5
#    
#    Available Tools:
#      1. tool1
#         Description of tool1
#      2. tool2
#         Description of tool2
```

### Security testing workflow

1. **Identify configured servers:**
   ```bash
   npm start -- servers
   # or
   node src/cli.js servers
   ```

2. **List all available tools:**
   ```bash
   npm start -- list
   # or
   node src/cli.js list
   ```

3. **Get detailed server information:**
   ```bash
   npm start -- info example-server
   # or
   node src/cli.js info example-server
   ```

4. **Export tool list for analysis:**
   ```bash
   npm start -- list --json > tools.json
   # or
   node src/cli.js list --json > tools.json
   ```

5. **Generate tool call templates:**
   ```bash
   # Generate a template for a specific tool
   npm start -- generate example-server list_emails_metadata
   # or
   node src/cli.js generate example-server list_emails_metadata
   
   # Generate and save to file
   node src/cli.js generate example-server list_emails_metadata --file
   ```

6. **Test tool execution:**
   ```bash
   # Test a tool with arguments (use generate first to get the template)
   npm start -- call example-server list_emails_metadata --args '{"account_id":"test","limit":5}'
   # or
   node src/cli.js call example-server list_emails_metadata --args '{"account_id":"test","limit":5}'
   
   # Or use the generated file
   node src/cli.js call example-server list_emails_metadata --args-file list_emails_metadata_args.json
   ```

## Security Considerations

This tool is designed to help security professionals:

- **Tool Enumeration**: Quickly identify all available tools in MCP servers
- **Configuration Analysis**: Review server configurations for potential vulnerabilities
- **Transport Security**: Test different transport mechanisms (stdio, SSE, HTTP/HTTPS)
- **Automation**: JSON output enables integration with security scanning tools
- **Template Generation**: Generate tool call templates for systematic testing

## Troubleshooting

### Server Warnings

Some MCP servers (particularly Python-based servers like Semgrep) may display warnings when connections are closed, such as:
```
WARNING Loop <_UnixSelectorEventLoop running=False closed=True> that handles pid X is closed
```

These warnings are **harmless** and come from the server process itself, not from this client. They occur when the server's event loop is being cleaned up and can be safely ignored.

### Connection Issues

If a server fails to connect:
- Check that the server command is available in your PATH
- Verify the server configuration in your `MCPserver.json` file
- Ensure required environment variables are set
- Check server logs for more detailed error messages

## License

MIT

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development and contribution guidelines.

mcp-lite

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README