gvaibhav/sample-mcp-server

Simple MCP Server

A comprehensive Model Context Protocol (MCP) server implementation with advanced capabilities including sampling, elicitation, and roots support.

Features

Core Capabilities

• Sampling: Server can request LLM completions from connected clients
• Elicitation: Interactive user input collection for complex workflows
• Roots: Root directory management for file operations
• Tools: File operations and AI-powered text processing
• Resources: Dynamic and static resource serving
• Prompts: Reusable prompt templates
• Notifications: Real-time activity notifications

Tools (4 available)

1. read-file - Read content from files
2. write-file - Write content to files with append support
3. summarize-text - AI-powered text summarization using sampling
4. interactive-booking - Interactive booking with user input via elicitation

Resources (3 types)

1. server-info (info://server) - Static server information
2. file://{path} - Dynamic file content serving
3. dir://{path} - Directory listing with metadata

Prompts (3 templates)

1. analyze-file - File content analysis prompt
2. dev-workflow - Development workflow guidance
3. server-status - Comprehensive server status report

Roots Support

The server provides access to the current working directory as a root, enabling:

• File system navigation
• Directory structure understanding
• Secure file operations within bounds

Usage

Testing with MCP Inspector

From Project Directory

# Build the server
npm run build

# Start MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

From Different Directory (Absolute Path)

When running MCP Inspector from a different location, use absolute paths:

Windows (PowerShell):

# Navigate to your desired working directory
cd C:\your\working\directory

# Run inspector with absolute path to the server
npx @modelcontextprotocol/inspector node "D:\gitRepositories\simple-mcp-server\build\index.js"

Windows (Command Prompt):

cd C:\your\working\directory
npx @modelcontextprotocol/inspector node "D:\gitRepositories\simple-mcp-server\build\index.js"

Linux/macOS:

cd /your/working/directory
npx @modelcontextprotocol/inspector node "/path/to/simple-mcp-server/build/index.js"

Direct stdio Communication

For direct stdio protocol communication (without inspector):

Node.js Integration

import { spawn } from 'child_process';

const serverProcess = spawn('node', ['D:\\gitRepositories\\simple-mcp-server\\build\\index.js'], {
  stdio: ['pipe', 'pipe', 'pipe']
});

// Send MCP messages via stdin
serverProcess.stdin.write(JSON.stringify({
  jsonrpc: '2.0',
  id: 1,
  method: 'initialize',
  params: {
    protocolVersion: '2024-11-05',
    capabilities: {},
    clientInfo: { name: 'test-client', version: '1.0.0' }
  }
}) + '\n');

// Listen for responses on stdout
serverProcess.stdout.on('data', (data) => {
  console.log('Server response:', data.toString());
});

Python Integration

import subprocess
import json

# Start the MCP server process
server_process = subprocess.Popen(
    ['node', r'D:\gitRepositories\simple-mcp-server\build\index.js'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True
)

# Send initialize message
init_message = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "python-client", "version": "1.0.0"}
    }
}

server_process.stdin.write(json.dumps(init_message) + '\n')
server_process.stdin.flush()

# Read response
response = server_process.stdout.readline()
print("Server response:", response)

VS Code MCP Extension

If using with VS Code MCP extension, add to your MCP configuration:

{
  "mcpServers": {
    "simple-mcp-server": {
      "command": "node",
      "args": ["D:\\gitRepositories\\simple-mcp-server\\build\\index.js"],
      "env": {}
    }
  }
}

Environment Variables

The server respects these environment variables:

• MCP_SERVER_NAME: Override server name (default: "simple-mcp-server")
• MCP_LOG_LEVEL: Set logging level (debug, info, warn, error)
• NODE_ENV: Set to "development" for additional debugging

Example:

$env:MCP_LOG_LEVEL = "debug"
node "D:\gitRepositories\simple-mcp-server\build\index.js"

Testing Individual Features

Sampling (summarize-text tool)

{
  "name": "summarize-text",
  "arguments": {
    "text": "Your text to summarize here...",
    "maxTokens": 200
  }
}

Elicitation (interactive-booking tool)

{
  "name": "interactive-booking", 
  "arguments": {
    "service": "restaurant",
    "date": "2024-12-25",
    "partySize": 4
  }
}

Roots

Access via "roots/list" to see available root directories.

Development

# Install dependencies
npm install

# Build
npm run build

# Start server
npm start

# Development mode
npm run dev

Architecture

• Transport: stdio protocol for MCP communication
• Security: File access restricted to current directory
• Error Handling: Comprehensive error catching and reporting
• Logging: Activity logging via stderr (doesn't interfere with stdio)

API Reference

The server implements the full MCP specification with extensions for:

• Sampling requests to connected LLM clients
• Elicitation requests for interactive user input
• Roots listing for file system access

All operations are logged and tracked for debugging and monitoring purposes.

Testing the New Features

1. Sampling Feature

Use the summarize-text tool with the provided sample-text.md file:

# In MCP Inspector, call the tool:
Tool: summarize-text
Arguments: {
  "text": "content of sample-text.md",
  "maxTokens": 150
}

2. Elicitation Feature

Use the interactive-booking tool to see interactive prompts:

# In MCP Inspector, call the tool:
Tool: interactive-booking
Arguments: {
  "service": "restaurant",
  "date": "2024-12-25", 
  "partySize": 2
}

3. Roots Feature

List available root directories:

# In MCP Inspector, use the roots/list method

VS Code Integration

The server includes VS Code MCP configuration in .vscode/mcp.json for easy integration with VS Code MCP features.