mcp-server by thecleanupcrew - MCP Server

MCP Help Request Server

A Model Context Protocol (MCP) server that provides tools for capturing comprehensive context about development issues and facilitating human assistance through structured API-based help requests.

Overview

This server provides tools that allow AI assistants to capture detailed context about coding issues, workspace state, and user conversations, then facilitate human support through automated session management and API integration.

Features

Comprehensive Context Capture: Automatically captures workspace state, file contents, error diagnostics, and conversation history
Structured Help Requests: Uses Zod schemas to ensure consistent and complete help request data
Session Management: Creates unique session IDs and logs for tracking help requests
API-Based Integration: Sends help requests to external APIs for human assistance coordination
Ticket-Based Integration: Creates structured support tickets through API integration
Modular Architecture: Clean separation of concerns with organized directory structure

Architecture

index.js             # Main entry point
src/
├── api/             # API integration layer
│   ├── index.js     # API exports
│   └── helpRequestAPI.js # Help request API client for ticket creation
├── config/          # Configuration files
│   └── logger.js    # Winston logger configuration
├── constants/       # Application constants
│   └── index.js     # Shared constants and configuration values
├── schemas/         # Zod validation schemas
│   └── helpRequest.js # Help request schema definitions
├── tools/           # MCP tool implementations
│   ├── index.js     # Tool exports
│   ├── helpRequest.js # Main help request tool
│   └── getHelpSession.js # Session retrieval tool
├── utils/           # Utility functions
│   └── workspace.js # Workspace analysis utilities
└── server.js        # Main server setup and configuration

logs/                # Log files and session data
sessions/            # Session storage
consent-records/     # Privacy consent records

Installation

Clone the repository
Install dependencies:
```
npm install
```

Usage

Starting the Server

npm run start

The server runs using the FastMCP framework with stdio transport.

Available Tools

1. `request_help`

Captures comprehensive context about a development issue and creates a support session.

Parameters:

session (required): Session information with unique ID and timestamp
conversation (required): Recent conversation messages leading to the help request
issue (required): Description of the problem that needs assistance
workspace (optional): Information about the user's workspace/project
diagnostics (optional): Error messages, warnings, or logs
solutionsAttempted (optional): Previous attempts to solve the issue
environment (optional): System environment details
dependencies (optional): Project dependencies
versionControl (optional): Git/version control information
performance (optional): Performance metrics

Returns:

Success message with ticket ID and status
Session ID for reference
Priority level assigned to ticket
Context summary
Next steps for the user

2. `get_help_session`

Retrieves the context data for a specific help session.

Parameters:

sessionId (required): The session ID to retrieve

Returns:

Session data in JSON format
Success/failure status

Configuration

Environment Variables

API_ENDPOINT: Ticket API endpoint (default: http://localhost:3000/api/tickets)
API_SERVICE_KEY: Service key for API authentication (default: your_mcp_service_key_here)
PORT: Server port (default: 8080)

Logger Configuration

The logger is configured in src/config/logger.js and creates:

Error logs: logs/error.log
Combined logs: logs/combined.log
Console output for development

Constants

Application constants are defined in src/constants/index.js:

Server configuration
API configuration options
File processing limits
Directory ignore patterns
Log levels

Development

Project Structure

The codebase follows a modular architecture:

API: External API integration for ticket creation
Config: Centralized configuration management
Schemas: Zod validation schemas for type safety
Tools: MCP tool implementations
Utils: Reusable utility functions
Constants: Shared application constants

API Configuration

The server integrates with a ticket API system. Configure the API endpoint and service key:

API_ENDPOINT=http://localhost:3000/api/tickets
API_SERVICE_KEY=your_service_key_here

Adding New Tools

Create a new tool file in src/tools/
Export the tool from src/tools/index.js
Add the tool to the server in src/server.js

Schema Validation

All tool parameters are validated using Zod schemas defined in src/schemas/. This ensures:

Type safety
Consistent data structure
Clear documentation of expected inputs

Dependencies

fastmcp: MCP server framework
winston: Logging
fs-extra: Enhanced file system operations
uuid: UUID generation
glob: File pattern matching
dotenv: Environment variable management

Logging

The server uses Winston for structured logging:

All help requests are logged with session IDs
Error conditions are captured with stack traces
Session data is stored in individual JSON files
Console output for development monitoring

Session Management

Each help request creates:

Unique session ID (UUID)
Timestamped session log file
Comprehensive context capture
API response with ticket ID and status

Error Handling

The server includes comprehensive error handling:

Graceful degradation when workspace access fails
Detailed error logging with context
User-friendly error messages
Session recovery capabilities
API failure handling with fallback responses

Privacy and Consent

The server includes built-in privacy protection:

User consent collection for data sharing
Consent record storage
Privacy-aware data handling

License

ISC License

Contributing

Follow the existing code structure
Add appropriate error handling
Include logging for debugging
Update documentation for new features
Ensure schema validation for new parameters
Test API integration with proper authentication