MCP Tools

A comprehensive Model Context Protocol (MCP) server providing utility tools for AI assistants. This server exposes 30+ tools across multiple categories to enhance AI capabilities with practical functionality.

Installation

Install from npm

npm install -g mcp-tools

Or install locally in your project:

npm install mcp-tools

Install from source

git clone https://github.com/YOUR_USERNAME/mcp-tools.git
cd mcp-tools
npm install
npm run build

Running the Server

npm start

Or if installed globally:

mcp-tools

For development with auto-rebuild:

npm run dev

Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

If installed globally:

{
  "mcpServers": {
    "mcp-tools": {
      "command": "mcp-tools"
    }
  }
}

If installed locally:

{
  "mcpServers": {
    "mcp-tools": {
      "command": "node",
      "args": ["./node_modules/mcp-tools/dist/index.js"]
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "mcp-tools": {
      "command": "node",
      "args": ["/path/to/mcp-tools/dist/index.js"]
    }
  }
}

Tools Reference

User Interaction Tools

Tools for interacting with users during workflows.

ask_user

Prompt the user for text input.

{
  "question": "What is your project name?",
  "default_value": "my-project"
}

Response: User's text input

confirm

Ask for yes/no confirmation.

{
  "message": "Do you want to proceed with the deployment?",
  "default_yes": false
}

Response: true or false

select

Present options for user selection.

{
  "message": "Choose a database:",
  "options": ["PostgreSQL", "MySQL", "SQLite"],
  "allow_multiple": false
}

Response: Selected option(s)

notify

Display a notification message.

{
  "message": "Build completed successfully!",
  "level": "success"
}

Levels: info, warning, error, success

progress

Display a progress indicator.

{
  "message": "Processing files...",
  "current": 45,
  "total": 100,
  "show_percentage": true
}

Output: Processing files... [45/100] 45%

JSON Tools

Tools for working with JSON data.

json_format

Format/prettify JSON with configurable indentation.

{
  "json": "{\"name\":\"test\",\"value\":123}",
  "indent": 2,
  "sort_keys": true
}

Output:

{
  "name": "test",
  "value": 123
}

json_validate

Validate JSON syntax and optionally check against a schema.

{
  "json": "{\"name\": \"John\", \"age\": 30}",
  "schema": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"age\": {\"type\": \"number\"}}, \"required\": [\"name\"]}"
}

Output: Validation result with any errors

json_extract

Extract values using dot notation paths.

{
  "json": "{\"data\": {\"items\": [{\"name\": \"first\"}, {\"name\": \"second\"}]}}",
  "path": "data.items[0].name"
}

Output: "first"

json_diff

Compare two JSON objects and show differences.

{
  "json1": "{\"name\": \"test\", \"value\": 1}",
  "json2": "{\"name\": \"test\", \"value\": 2, \"new\": true}"
}

Output:

changed: value: 1 -> 2
added: new: true

Code Tools

Tools for code analysis and formatting.

code_format

Format code using language-specific formatters.

{
  "code": "function hello(){return 'world'}",
  "language": "js"
}

Output:

function hello() {
  return "world";
}

Supported Languages:

• js, ts, jsx, tsx - Uses Prettier
• python, py - Uses Black
• go - Uses gofmt

code_lint

Run linting on code and return issues.

{
  "code": "var x = 1;\nconsole.log(y);",
  "language": "js",
  "rules": ["no-unused-vars", "no-undef"]
}

Output: List of linting issues with line numbers

code_diff

Generate a diff between two code snippets.

{
  "original": "function add(a, b) {\n  return a + b;\n}",
  "modified": "function add(a, b) {\n  // Add two numbers\n  return a + b;\n}",
  "context_lines": 3
}

Output: Unified diff format with statistics

code_analyze

Analyze code structure and provide metrics.

{
  "code": "class User {\n  constructor(name) {\n    this.name = name;\n  }\n  greet() {\n    return `Hello, ${this.name}`;\n  }\n}",
  "language": "js"
}

Output:

{
  "lines": { "total": 8, "code": 8, "blank": 0 },
  "functions": 2,
  "classes": 1,
  "complexity": { "conditionals": 0, "loops": 0 }
}

File & Git Tools

Tools for file system and git operations.

file_tree

Generate a tree view of directory structure.

{
  "path": "/path/to/project",
  "max_depth": 2,
  "ignore": ["node_modules", ".git"],
  "format": "tree"
}

Output:

project/
  src/
    index.ts
    utils.ts
  package.json
  README.md

file_search

Search for files by name pattern or content.

{
  "path": "/path/to/project",
  "pattern": "*.ts",
  "type": "name",
  "max_results": 10
}

Output: List of matching file paths

For content search:

{
  "path": "/path/to/project",
  "pattern": "TODO:",
  "type": "content"
}

git_status

Get the current git status.

{
  "path": "/path/to/repo",
  "porcelain": false
}

Output: Git status output

git_diff

Get git diff output.

{
  "path": "/path/to/repo",
  "staged": true,
  "file": "src/index.ts"
}

Output: Diff output with statistics

Format Tools

Tools for formatting output.

format_table

Format data as an ASCII table.

{
  "headers": ["Name", "Age", "City"],
  "rows": [
    ["Alice", "30", "New York"],
    ["Bob", "25", "San Francisco"]
  ],
  "border": "simple",
  "align": "left"
}

Output:

+-------+-----+---------------+
| Name  | Age | City          |
+-------+-----+---------------+
| Alice | 30  | New York      |
| Bob   | 25  | San Francisco |
+-------+-----+---------------+

format_markdown

Format content as markdown elements.

{
  "content": "Important Note",
  "type": "heading",
  "level": 2
}

Output: ## Important Note

Types: heading, list, blockquote, link, bold, italic, code

format_code_block

Format code as a fenced code block.

{
  "code": "const x = 1;\nconst y = 2;",
  "language": "javascript",
  "line_numbers": true,
  "start_line": 1
}

Output:

```javascript
1 | const x = 1;
2 | const y = 2;
```

State Management Tools

Tools for persisting and managing state.

state_save

Save state data with a key.

{
  "key": "user_preferences",
  "data": "{\"theme\": \"dark\", \"language\": \"en\"}",
  "namespace": "settings"
}

state_load

Load previously saved state data.

{
  "key": "user_preferences",
  "namespace": "settings"
}

Output: Saved data or error if not found

checkpoint

Create a named checkpoint of state values.

{
  "name": "before_migration",
  "description": "State before database migration",
  "include_namespaces": ["settings", "cache"]
}

checkpoint_restore

Restore state from a checkpoint.

{
  "name": "before_migration",
  "namespaces": ["settings"]
}

Debug Tools

Tools for debugging and performance measurement.

debug_log

Log debug messages with context.

{
  "message": "Processing request",
  "level": "info",
  "context": {"requestId": "abc123", "userId": 42},
  "to_file": true
}

Levels: debug, info, warn, error

debug_time_start

Start a named timer.

{
  "name": "api_call",
  "description": "External API request"
}

debug_time_end

End a timer and get elapsed time.

{
  "name": "api_call",
  "log_result": true
}

Output: Timer 'api_call' completed in 1.234s

Utility Tools

General utility tools.

app_status

Check if an app/process is running after executing a command.

{
  "command": "npm start",
  "process_name": "node",
  "port": 3000,
  "timeout": 5000
}

Use Cases:

• Execute a command and verify the app started
• Check if a process is running by name
• Check if a port is in use
• Combine all checks together

Example 1: Check if server is running on port

{
  "port": 3000
}

Example 2: Start app and verify it's running

{
  "command": "npm start &",
  "port": 8080,
  "timeout": 10000
}

Example 3: Check process by name

{
  "process_name": "nginx"
}

Response:

{
  "running": true,
  "command_executed": true,
  "command_output": "Server started",
  "command_error": null,
  "process_running": true,
  "port_in_use": true,
  "pid": 12345,
  "details": "Process 'node' is running. Port 3000 is in use."
}

validate_schema

Validate data against a JSON schema.

{
  "data": "{\"name\": \"John\", \"email\": \"[email protected]\"}",
  "schema": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"email\": {\"type\": \"string\", \"format\": \"email\"}}, \"required\": [\"name\", \"email\"]}"
}

http_request

Make HTTP requests.

{
  "url": "https://api.example.com/users",
  "method": "POST",
  "headers": {"Content-Type": "application/json"},
  "body": "{\"name\": \"John\"}",
  "timeout": 30000
}

Methods: GET, POST, PUT, DELETE, PATCH

template_render

Render templates with variable substitution.

{
  "template": "Hello, {{name}}! Welcome to {{app}}.",
  "variables": {"name": "John", "app": "MCP Tools"},
  "strict": false
}

Output: Hello, John! Welcome to MCP Tools.

Storage Locations

The server uses temporary directories for persistence:

| Purpose | Location | |---------|----------| | State data | /tmp/mcp_state/ | | Checkpoints | /tmp/mcp_checkpoints/ | | Debug logs | /tmp/mcp_debug.log |

Development

Project Structure

mcp-tools/
  src/
    index.ts              # Main server entry point
    tools/
      code-tools.ts       # Code formatting & analysis
      debug-tools.ts      # Debug & timing utilities
      file-git-tools.ts   # File & git operations
      format-tools.ts     # Output formatting
      json-tools.ts       # JSON manipulation
      state-tools.ts      # State persistence
      user-interaction.ts # User prompts
      utility-tools.ts    # HTTP, templates, validation
  dist/                   # Compiled output
  package.json
  tsconfig.json

Adding New Tools

1. Create or update a tool file in src/tools/
2. Define the tool with Zod schema:

import { z } from "zod";

export const myTools = {
  my_tool: {
    description: "Description of what the tool does",
    inputSchema: z.object({
      param1: z.string().describe("Parameter description"),
      param2: z.number().optional().default(10),
    }),
    handler: async (args: { param1: string; param2: number }) => {
      // Implementation
      return { content: [{ type: "text", text: "Result" }] };
    },
  },
};

3. Import and spread in src/index.ts:

import { myTools } from "./tools/my-tools.js";

const allTools = {
  ...existingTools,
  ...myTools,
};

4. Rebuild: npm run build

License

MIT