test-mcp-utilities

Andre-Buzeli/test-mcp-utilities

3.2

If you are the rightful owner of test-mcp-utilities and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A comprehensive Model Context Protocol (MCP) server implementation for testing Roots, Sampling, and Elicitation features across different IDEs.

Tools
4
Resources
0
Prompts
0

@andrebuzeli/test-mcp-utilities

A comprehensive Model Context Protocol (MCP) server implementation for testing Roots, Sampling, and Elicitation features across different IDEs. Designed for use with npx and configured in MCP settings.

Overview

This package provides a complete MCP server with four essential tools designed to test and demonstrate the core MCP capabilities:

  1. Roots Boundaries - File system access control and boundary definition
  2. Project Info - Get current project name and directory information
  3. Sampling Request - LLM completion requests through the client
  4. Elicitation Request - Dynamic user information gathering with structured schemas

Features

  • ✅ Roots Management: Define file system boundaries with configurable access control
  • ✅ Project Detection: Automatically detect and return current project information
  • ✅ LLM Sampling: Request completions through the MCP client with customizable parameters
  • ✅ User Elicitation: Gather structured information from users with JSON schema validation
  • ✅ Cross-IDE Compatibility: Tested across Trae AI, VSCode, and Cursor AI
  • ✅ TypeScript Support: Full TypeScript implementation with type definitions
  • ✅ Error Handling: Comprehensive error handling and validation
  • ✅ NPX Ready: Configured for direct use with npx command

Installation & Configuration

Global Installation (Recommended)

npm install -g @andrebuzeli/test-mcp-utilities

NPX Usage (No Installation Required)

npx @andrebuzeli/test-mcp-utilities

MCP Configuration

Add to your MCP settings file (usually located at %APPDATA%\mcp\mcp.json on Windows or ~/.config/mcp/mcp.json on macOS/Linux):

{
  "mcpServers": {
    "test-mcp-utilities": {
      "command": "npx",
      "args": ["@andrebuzeli/test-mcp-utilities"]
    }
  }
}

IDE-Specific Configuration

Trae AI

Add to your Trae AI MCP settings:

{
  "mcpServers": {
    "test-mcp-utilities": {
      "command": "npx",
      "args": ["@andrebuzeli/test-mcp-utilities"]
    }
  }
}
VSCode with MCP Extension

Configure in your VSCode MCP extension settings:

{
  "mcp.servers": {
    "test-mcp-utilities": {
      "command": "npx",
      "args": ["@andrebuzeli/test-mcp-utilities"]
    }
  }
}
Cursor AI

Add to your Cursor AI MCP configuration:

{
  "mcpServers": {
    "test-mcp-utilities": {
      "command": "npx",
      "args": ["@andrebuzeli/test-mcp-utilities"]
    }
  }
}

Tools Documentation

1. roots_boundaries

Define file system boundaries for server access control.

Parameters:

  • rootPath (required): Root directory path to set as boundary
  • allowedExtensions (optional): Array of allowed file extensions
  • excludePaths (optional): Array of paths to exclude from access

Example:

{
  "rootPath": "/path/to/project",
  "allowedExtensions": [".js", ".ts", ".json"],
  "excludePaths": ["node_modules", ".git"]
}

2. get_project_info

Returns information about the currently opened project in the IDE.

Parameters:

  • includeStats (optional): Include additional project statistics (default: false)

Example Response:

{
  "projectName": "my-project",
  "projectPath": "/path/to/my-project",
  "timestamp": "2025-01-26T10:30:00.000Z",
  "statistics": {
    "totalFiles": 45,
    "directories": 8,
    "lastModified": "2025-01-26T09:15:00.000Z"
  }
}

3. sampling_request

Request LLM completions through the client for agentic behaviors.

Parameters:

  • prompt (required): The prompt to send to the LLM
  • maxTokens (optional): Maximum tokens to generate (default: 1000)
  • temperature (optional): Sampling temperature 0.0-1.0 (default: 0.7)
  • modelPreference (optional): Preferred model to use

Example:

{
  "prompt": "Explain the concept of MCP in simple terms",
  "maxTokens": 500,
  "temperature": 0.5,
  "modelPreference": "gpt-4"
}

4. elicitation_request

Dynamically gather specific information from users using structured schemas.

Parameters:

  • requestTitle (required): Title for the information request
  • requestDescription (required): Description of what information is needed
  • schema (required): JSON schema defining the required information structure
  • allowCancel (optional): Whether user can cancel the request (default: true)

Example:

{
  "requestTitle": "Project Configuration",
  "requestDescription": "Please provide your project configuration details",
  "schema": {
    "type": "object",
    "properties": {
      "projectName": {"type": "string"},
      "version": {"type": "string"},
      "author": {"type": "string"}
    },
    "required": ["projectName", "version"]
  },
  "allowCancel": true
}

Quick Start

  1. Install globally or use npx:

    npm install -g @andrebuzeli/test-mcp-utilities
# OR
npx @andrebuzeli/test-mcp-utilities

  2. Configure in your IDE's MCP settings:

    {
  "mcpServers": {
    "test-mcp-utilities": {
      "command": "npx",
      "args": ["@andrebuzeli/test-mcp-utilities"]
    }
  }
}

  3. Restart your IDE and the tools will be available in your MCP-enabled environment.

IDE Compatibility

This package has been tested and verified to work with:

  • Trae AI - Full compatibility with all features
  • VSCode - Compatible with MCP extension
  • Cursor AI - Full MCP protocol support

Development

Building from Source

git clone https://github.com/andrebuzeli/test-mcp-utilities.git
cd test-mcp-utilities
npm install
npm run build

Running Tests

npm test

Local Development

npm run dev

API Reference

Server Capabilities

The server announces the following capabilities:

{
  "capabilities": {
    "tools": {},
    "sampling": {},
    "roots": {
      "listChanged": true
    }
  }
}

Error Handling

All tools implement comprehensive error handling and return structured error responses:

{
  "content": [
    {
      "type": "text",
      "text": "Error executing tool: [error message]"
    }
  ],
  "isError": true
}

Troubleshooting

Common Issues

  1. Command not found: Make sure Node.js is installed and npx is available in your PATH.
  2. Permission errors: On some systems, you may need to run with elevated permissions.
  3. MCP not connecting: Verify your MCP configuration file syntax and restart your IDE.

Configuration File Locations

  • Windows: %APPDATA%\mcp\mcp.json
  • macOS: ~/.config/mcp/mcp.json
  • Linux: ~/.config/mcp/mcp.json

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

MIT License - see the file for details.

Author

Andre Buzeli

Changelog

v1.0.0

  • Initial release
  • Implemented all four core tools
  • Added TypeScript support
  • Cross-IDE compatibility testing
  • NPX configuration support
  • Comprehensive documentation

Support

If you encounter any issues or have questions, please:

  1. Check the Issues page
  2. Create a new issue with detailed information
  3. Include your IDE version and MCP configuration

Keywords: MCP, Model Context Protocol, Roots, Sampling, Elicitation, IDE, VSCode, Cursor, Trae AI, TypeScript, NPX, MCP Server

Tools Documentation

1. roots_boundaries

Define file system boundaries for server access control.

Parameters:

  • rootPath (required): Root directory path to set as boundary
  • allowedExtensions (optional): Array of allowed file extensions
  • excludePaths (optional): Array of paths to exclude from access

Example:

{
  "rootPath": "/path/to/project",
  "allowedExtensions": [".js", ".ts", ".json"],
  "excludePaths": ["node_modules", ".git"]
}

2. get_project_info

Returns information about the currently opened project in the IDE.

Parameters:

  • includeStats (optional): Include additional project statistics (default: false)

Example Response:

{
  "projectName": "my-project",
  "projectPath": "/path/to/my-project",
  "timestamp": "2025-01-26T10:30:00.000Z",
  "statistics": {
    "totalFiles": 45,
    "directories": 8,
    "lastModified": "2025-01-26T09:15:00.000Z"
  }
}

3. sampling_request

Request LLM completions through the client for agentic behaviors.

Parameters:

  • prompt (required): The prompt to send to the LLM
  • maxTokens (optional): Maximum tokens to generate (default: 1000)
  • temperature (optional): Sampling temperature 0.0-1.0 (default: 0.7)
  • modelPreference (optional): Preferred model to use

Example:

{
  "prompt": "Explain the concept of MCP in simple terms",
  "maxTokens": 500,
  "temperature": 0.5,
  "modelPreference": "gpt-4"
}

4. elicitation_request

Dynamically gather specific information from users using structured schemas.

Parameters:

  • requestTitle (required): Title for the information request
  • requestDescription (required): Description of what information is needed
  • schema (required): JSON schema defining the required information structure
  • allowCancel (optional): Whether user can cancel the request (default: true)

Example:

{
  "requestTitle": "Project Configuration",
  "requestDescription": "Please provide your project configuration details",
  "schema": {
    "type": "object",
    "properties": {
      "projectName": {"type": "string"},
      "version": {"type": "string"},
      "author": {"type": "string"}
    },
    "required": ["projectName", "version"]
  },
  "allowCancel": true
}

IDE Compatibility

This package has been tested and verified to work with:

  • Trae AI - Full compatibility with all features
  • VSCode - Compatible with MCP extension
  • Cursor AI - Full MCP protocol support

Development

Building from Source

git clone https://github.com/andrebuzeli/test-mcp-utilities.git
cd test-mcp-utilities
npm install
npm run build

Running Tests

npm test

Local Development

npm run dev

API Reference

Server Capabilities

The server announces the following capabilities:

{
  "capabilities": {
    "tools": {},
    "sampling": {},
    "roots": {
      "listChanged": true
    }
  }
}

Error Handling

All tools implement comprehensive error handling and return structured error responses:

{
  "content": [
    {
      "type": "text",
      "text": "Error executing tool: [error message]"
    }
  ],
  "isError": true
}

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

MIT License - see the file for details.

Author

Andre Buzeli

Changelog

v1.0.0

  • Initial release
  • Implemented all four core tools
  • Added TypeScript support
  • Cross-IDE compatibility testing
  • Comprehensive documentation

Support

If you encounter any issues or have questions, please:

  1. Check the Issues page
  2. Create a new issue with detailed information
  3. Include your IDE version and MCP configuration

Keywords: MCP, Model Context Protocol, Roots, Sampling, Elicitation, IDE, VSCode, Cursor, Trae AI, TypeScript