Add development tools and documentation

CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to mcp-cli
+
+Thank you for your interest in contributing to mcp-cli! This guide will help you get set up for development and understand our workflow.
+
+## Development Environment Setup
+
+### Prerequisites
+- Node.js (version 18 or higher)
+- pnpm (package manager)
+
+### Initial Setup
+```bash
+# Clone the repository
+git clone https://github.com/wong2/mcp-cli.git
+cd mcp-cli
+
+# Install dependencies
+pnpm install
+```
+
+## Development Workflow
+
+### Test Servers
+The project includes comprehensive test servers for all MCP transport types, located in `test/servers/`:
+
+- **stdio-server.js** - Standard input/output transport
+- **http-server.js** - HTTP transport (port 9100)
+- **sse-server.js** - Server-Sent Events transport (port 9101)
+- **simple-http-server.js** - Simplified HTTP server
+
+### Starting Test Servers
+```bash
+# Start individual servers
+pnpm run server:stdio    # Stdio server (foreground)
+pnpm run server:http     # HTTP server on port 9100
+pnpm run server:sse      # SSE server on port 9101
+
+# See available server commands
+pnpm run server:help
+```
+
+### Testing Your Changes
+```bash
+# Test with different transport types
+pnpm run test:stdio      # Test stdio transport
+pnpm run test:http       # Test HTTP transport (requires HTTP server running)
+pnpm run test:sse        # Test SSE transport (requires SSE server running)
+
+# Test with config file
+npx mcp-cli -c test/config.json stdio-server
+
+# Test direct server connections
+npx mcp-cli --url http://localhost:9100/mcp
+npx mcp-cli --sse http://localhost:9101/sse
+```
+
+### Manual Testing Scenarios
+1. **Interactive Mode**: Test all MCP primitives (tools, resources, prompts)
+2. **Non-Interactive Mode**: Test list commands (`list-tools`, `list-resources`, etc.)
+3. **Configuration**: Test both config file and direct connection methods
+4. **Transport Types**: Verify all three transport types work correctly
+5. **OAuth Flows**: Test authentication with protected servers
+
+## Code Standards
+
+### Formatting
+We use Prettier for code formatting. Configuration is in `.prettierrc`.
+
+```bash
+# Format code (if you have prettier installed globally)
+npx prettier --write .
+```
+
+### Code Quality
+- Follow existing patterns in the codebase
+- Add error handling for new features
+- Ensure compatibility with all transport types
+- Test both interactive and non-interactive modes
+
+## Architecture Overview
+
+### Key Files
+- `src/cli.js` - Main CLI entry point and argument parsing
+- `src/mcp.js` - Core MCP client logic and connection handling
+- `src/config.js` - Configuration file loading and validation
+- `src/oauth/` - OAuth authentication providers
+- `src/utils.js` - Shared utility functions
+
+### Transport Support
+The CLI supports three MCP transport types:
+1. **Stdio** - Process-based communication via stdin/stdout
+2. **HTTP** - Modern HTTP-based transport with session management
+3. **SSE** - Server-Sent Events (legacy transport)
+
+## Making Changes
+
+### Branch Naming
+Use descriptive branch names:
+- `feat/new-feature-name`
+- `fix/bug-description`
+- `docs/documentation-update`
+
+### Testing Checklist
+Before submitting a PR, verify:
+- [ ] All transport types work (stdio, HTTP, SSE)
+- [ ] Interactive mode functions correctly
+- [ ] Non-interactive list commands work
+- [ ] Configuration file loading works
+- [ ] No regression in existing functionality
+- [ ] Code follows existing style patterns
+
+### Pull Request Process
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Make your changes with clear commit messages
+4. Test thoroughly using the test servers
+5. Submit a pull request with a clear description
+
+## Getting Help
+
+- Check existing issues for similar problems
+- Use the test servers to reproduce and debug issues
+- Look at the `docs/` directory for detailed technical documentation
+- Examine existing code patterns for guidance
+
+## Development Tips
+
+- Use `test/config.json` for testing configuration-based connections
+- The test servers provide identical functionality across all transport types
+- OAuth testing can be done with the HTTP and SSE servers
+- Environment variables can be tested with the stdio server using `--pass-env`
+
+Thank you for contributing to mcp-cli!

README.md

@@ -85,6 +85,10 @@ This mode is useful for scripting and automation, as it bypasses all interactive
 npx @wong2/mcp-cli purge
 ```
 
+## Development
+
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and workflow
+
 ## Related
 
 - [mcpservers.org](https://mcpservers.org) - A curated list of MCP servers

package.json

@@ -11,7 +11,15 @@
     "src",
     "README.md"
   ],
-  "scripts": {},
+  "scripts": {
+    "server:stdio": "node test/servers/stdio-server.js",
+    "server:http": "node test/servers/http-server.js",
+    "server:sse": "node test/servers/sse-server.js",
+    "server:help": "echo 'Available servers: stdio (pnpm run server:stdio), http (pnpm run server:http), sse (pnpm run server:sse)'",
+    "test:stdio": "node src/cli.js node test/servers/stdio-server.js",
+    "test:http": "node src/cli.js --url http://localhost:9100/mcp",
+    "test:sse": "node src/cli.js --sse http://localhost:9101/sse"
+  },
   "keywords": [
     "MCP"
   ],

test/config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "stdio-server": {
+      "command": "node",
+      "args": ["test/servers/stdio-server.js"]
+    },
+    "http-server": {
+      "url": "http://localhost:9100/mcp"
+    },
+    "sse-server": {
+      "url": "http://localhost:9101/sse"
+    }
+  }
+}

test/servers/README.md

@@ -0,0 +1,162 @@
+# MCP Test Servers
+
+This directory contains test servers for all three MCP transport types to help test and demonstrate MCP connectivity.
+
+## Servers
+
+### Stdio Server (`stdio-server.js`)
+- **Transport**: StdioServerTransport 
+- **Communication**: stdin/stdout
+- **Features**: Standard MCP stdio protocol
+
+### HTTP Server (`http-server.js`)
+- **Port**: 9100
+- **Transport**: StreamableHTTPServerTransport
+- **Endpoint**: `http://localhost:9100/mcp`
+- **Features**: Session management, modern HTTP transport
+
+### SSE Server (`sse-server.js`)
+- **Port**: 9101
+- **Transport**: SSEServerTransport (Legacy)
+- **SSE Endpoint**: `http://localhost:9101/sse`
+- **Messages Endpoint**: `http://localhost:9101/messages`
+- **Features**: Server-Sent Events streaming
+
+## Usage
+
+### Starting the Servers
+
+Using npm scripts (recommended):
+```bash
+# Start stdio server (runs in foreground)
+pnpm run server:stdio
+
+# Start HTTP server
+pnpm run server:http
+
+# Start SSE server (in another terminal)
+pnpm run server:sse
+
+# Test stdio client connection (launches server directly)
+pnpm run test:stdio
+
+# Test HTTP client connection (requires HTTP server to be running)
+pnpm run test:http
+
+# Test SSE client connection (requires SSE server to be running)
+pnpm run test:sse
+```
+
+Or using node directly:
+```bash
+# Start stdio server
+node test/servers/stdio-server.js
+
+# Start HTTP server
+node test/servers/http-server.js
+
+# Start SSE server (in another terminal)
+node test/servers/sse-server.js
+```
+
+### Testing with mcp-cli
+
+```bash
+# Test stdio server (direct command - recommended)
+mcp-cli node test/servers/stdio-server.js
+
+# Test stdio server (from config - alternative)
+mcp-cli --config mcp_config.json stdio-server
+
+# Test HTTP server
+mcp-cli --url http://localhost:9100/mcp
+
+# Test SSE server
+mcp-cli --sse http://localhost:9101/sse
+```
+
+## Available Features
+
+All three servers provide identical MCP functionality:
+
+### Tools
+- **add**: Add two numbers together
+  - Parameters: `a` (number), `b` (number)
+- **echo**: Echo back input text
+  - Parameters: `message` (string)
+- **current-time**: Get current timestamp
+  - Parameters: none
+
+### Resources
+- **server-info://status**: Server information and status
+  - Returns JSON with server details, version, transport type, etc.
+
+## Health Checks
+
+Both servers provide health check endpoints:
+
+```bash
+# HTTP server health
+curl http://localhost:9100/health
+
+# SSE server health
+curl http://localhost:9101/health
+```
+
+## Example Interactions
+
+### Using Tools
+```bash
+# Test addition tool
+{"method": "call_tool", "params": {"name": "add", "arguments": {"a": 5, "b": 3}}}
+
+# Test echo tool
+{"method": "call_tool", "params": {"name": "echo", "arguments": {"message": "Hello MCP!"}}}
+
+# Test time tool
+{"method": "call_tool", "params": {"name": "current-time", "arguments": {}}}
+```
+
+### Reading Resources
+```bash
+# Get server information
+{"method": "read_resource", "params": {"uri": "server-info://status"}}
+```
+
+## Transport Differences
+
+### Stdio
+- Standard transport for command-line tools
+- Uses stdin/stdout for communication
+- Most compatible and widely supported
+- Process-based isolation
+
+### HTTP (StreamableHTTP)
+- Modern transport protocol
+- Single endpoint handles all requests
+- Built-in session management
+- Better error handling and resilience
+- Supports resumable connections
+
+### SSE (Server-Sent Events)
+- Legacy transport (deprecated)
+- Separate endpoints for SSE stream and messages
+- Simpler but less robust
+- Limited error recovery
+
+## Testing All Transports
+
+These servers allow you to test the differences between stdio, HTTP and SSE transports:
+
+1. **Performance**: Compare response times and throughput
+2. **Reliability**: Test connection handling and recovery
+3. **Features**: Verify all MCP features work on all transports
+4. **Client Compatibility**: Ensure clients work with all transport protocols
+
+## Notes
+
+- All three servers use the same MCP SDK (`@modelcontextprotocol/sdk`)
+- DNS rebinding protection is enabled for security
+- Graceful shutdown is implemented (Ctrl+C)
+- Session management tracks active connections
+- All endpoints include proper error handling