hotjoebq/hjmcpstdio

MCP Stdio Server

A complete Model Context Protocol (MCP) server implementation using stdio transport that showcases:

• Resources: File system access to read project files (README.md, package.json, src/server.ts)
• Tools: Calculator for mathematical operations and file listing
• Prompts: Code review and code explanation assistants

Features

• MCP server with stdio transport
• File reading resources for project files
• Mathematical calculator tool
• Directory listing tool
• Code review and explanation prompt templates
• VSCode integration ready
• Test client for basic functionality testing

Setup

1. Install dependencies:

npm install

2. Build the project:

npm run build

Testing Options

Option 1: Basic Functionality Test (No Additional Tools Required)

npm run test-simple

This runs a simple client that tests basic MCP communication with the server.

Option 2: Comprehensive Testing (Requires mcp-cli Installation)

First, install mcp-cli globally:

npm install -g @modelcontextprotocol/cli

Then run comprehensive tests:

# Set the MCP configuration
export MCP_CLI_CONFIG_PATH=$(pwd)/mcp_config.json
# On Windows Command Prompt, use: set MCP_CLI_CONFIG_PATH=%cd%\mcp_config.json

# List available tools
mcp-cli tool list --server hjmcp-stdio

# Test calculator tool
mcp-cli tool call calculate --server hjmcp-stdio --input '{"expression": "2 + 3 * 4"}'

# Test file listing tool
mcp-cli tool call list_files --server hjmcp-stdio --input '{"directory": "."}'

# Test resource reading
mcp-cli tool read file://package.json --server hjmcp-stdio

VSCode Integration (No mcp-cli Required)

VSCode has built-in MCP support and connects directly to your server. You do NOT need to install mcp-cli for VSCode integration.

Add this to your VSCode MCP settings to use this server:

{
  "mcpServers": {
    "hjmcp-stdio": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/absolute/path/to/your/hjmcpstdio/directory",
      "transport": "stdio"
    }
  }
}

Important Notes:

• Replace /absolute/path/to/your/hjmcpstdio/directory with the actual absolute path to this project directory
• Make sure you've run npm run build first to compile the TypeScript
• VSCode will handle all MCP communication automatically - no additional tools needed

Available npm Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode compilation
• npm run start - Run the MCP server directly
• npm run test-simple - Run basic client test
• npm run clean - Remove build files

Server Capabilities

Resources

• file://README.md - Project documentation
• file://package.json - Package configuration
• file://src/server.ts - Server source code

Tools

• calculate - Perform mathematical calculations
  • Input: {"expression": "mathematical expression"}
  • Example: {"expression": "2 + 3 * 4"}
• list_files - List files in a directory
  • Input: {"directory": "relative path"} (optional, defaults to ".")
  • Example: {"directory": "src"}

Prompts

• code-review - Get code review suggestions
  • Arguments: file_path (required), focus_areas (optional)
• explain-code - Get code explanations
  • Arguments: code_snippet (required), language (optional)

Project Structure

• src/server.ts - Main MCP server implementation
• src/simple-client.ts - Basic test client
• mcp_config.json - MCP CLI configuration for testing
• package.json - Project configuration and dependencies
• tsconfig.json - TypeScript configuration

Testing Summary

Quick Testing (No Additional Setup):

• Use npm run test-simple for basic functionality verification

Comprehensive Testing (Requires mcp-cli):

• Install mcp-cli globally: npm install -g @modelcontextprotocol/cli
• Use mcp-cli commands for detailed tool and resource testing

VSCode Integration (No mcp-cli Needed):

• Add server configuration to VSCode MCP settings
• VSCode handles MCP communication automatically

The server has been tested with:

• ✅ Tool functionality (calculate, list_files)
• ✅ Resource reading (package.json confirmed working)
• ✅ Stdio transport communication
• ✅ MCP protocol compliance
• ✅ Cross-platform compatibility (Windows, macOS, Linux)