A Model Context Protocol (MCP) server providing 30+ utility tools for AI assistants, including user interaction, JSON manipulation, code formatting, file/git operations, state management, and debugging utilities
npm install utility-mcp-toolsA 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.
``bash`
npm install -g mcp-tools
Or install locally in your project:
`bash`
npm install mcp-tools
`bash`
git clone https://github.com/YOUR_USERNAME/mcp-tools.git
cd mcp-tools
npm install
npm run build
`bash`
npm start
Or if installed globally:
`bash`
mcp-tools
For development with auto-rebuild:
`bash`
npm run dev
Add to your MCP client configuration (e.g., Claude Desktop):
`json`
{
"mcpServers": {
"mcp-tools": {
"command": "mcp-tools"
}
}
}
`json`
{
"mcpServers": {
"mcp-tools": {
"command": "node",
"args": ["./node_modules/mcp-tools/dist/index.js"]
}
}
}
`json`
{
"mcpServers": {
"mcp-tools": {
"command": "node",
"args": ["/path/to/mcp-tools/dist/index.js"]
}
}
}
---
Tools for interacting with users during workflows.
#### ask_user
Prompt the user for text input.
`json`
{
"question": "What is your project name?",
"default_value": "my-project"
}
Response: User's text input
---
#### confirm
Ask for yes/no confirmation.
`json`
{
"message": "Do you want to proceed with the deployment?",
"default_yes": false
}
Response: true or false
---
#### select
Present options for user selection.
`json`
{
"message": "Choose a database:",
"options": ["PostgreSQL", "MySQL", "SQLite"],
"allow_multiple": false
}
Response: Selected option(s)
---
#### notify
Display a notification message.
`json`
{
"message": "Build completed successfully!",
"level": "success"
}
Levels: info, warning, error, success
---
#### progress
Display a progress indicator.
`json`
{
"message": "Processing files...",
"current": 45,
"total": 100,
"show_percentage": true
}
Output: Processing files... [45/100] 45%
---
Tools for working with JSON data.
#### json_format
Format/prettify JSON with configurable indentation.
`json`
{
"json": "{\"name\":\"test\",\"value\":123}",
"indent": 2,
"sort_keys": true
}
Output:
`json`
{
"name": "test",
"value": 123
}
---
#### json_validate
Validate JSON syntax and optionally check against a schema.
`json`
{
"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`
{
"json": "{\"data\": {\"items\": [{\"name\": \"first\"}, {\"name\": \"second\"}]}}",
"path": "data.items[0].name"
}
Output: "first"
---
#### json_diff
Compare two JSON objects and show differences.
`json`
{
"json1": "{\"name\": \"test\", \"value\": 1}",
"json2": "{\"name\": \"test\", \"value\": 2, \"new\": true}"
}
Output:
`
changed: value: 1 -> 2
added: new: true
---
Tools for code analysis and formatting.
#### code_format
Format code using language-specific formatters.
`json`
{
"code": "function hello(){return 'world'}",
"language": "js"
}
Output:
`javascript`
function hello() {
return "world";
}
Supported Languages:
- js, ts, jsx, tsx - Uses Prettierpython
- , py - Uses Blackgo
- - Uses gofmt
---
#### code_lint
Run linting on code and return issues.
`json`
{
"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.
`json`
{
"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.
`jsonHello, ${this.name}
{
"code": "class User {\n constructor(name) {\n this.name = name;\n }\n greet() {\n return ;\n }\n}",`
"language": "js"
}
Output:
`json`
{
"lines": { "total": 8, "code": 8, "blank": 0 },
"functions": 2,
"classes": 1,
"complexity": { "conditionals": 0, "loops": 0 }
}
---
Tools for file system and git operations.
#### file_tree
Generate a tree view of directory structure.
`json`
{
"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.
`json`
{
"path": "/path/to/project",
"pattern": "*.ts",
"type": "name",
"max_results": 10
}
Output: List of matching file paths
For content search:
`json`
{
"path": "/path/to/project",
"pattern": "TODO:",
"type": "content"
}
---
#### git_status
Get the current git status.
`json`
{
"path": "/path/to/repo",
"porcelain": false
}
Output: Git status output
---
#### git_diff
Get git diff output.
`json`
{
"path": "/path/to/repo",
"staged": true,
"file": "src/index.ts"
}
Output: Diff output with statistics
---
Tools for formatting output.
#### format_table
Format data as an ASCII table.
`json`
{
"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.
`json`
{
"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.
`json`
{
"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;
---
Tools for persisting and managing state.
#### state_save
Save state data with a key.
`json`
{
"key": "user_preferences",
"data": "{\"theme\": \"dark\", \"language\": \"en\"}",
"namespace": "settings"
}
---
#### state_load
Load previously saved state data.
`json`
{
"key": "user_preferences",
"namespace": "settings"
}
Output: Saved data or error if not found
---
#### checkpoint
Create a named checkpoint of state values.
`json`
{
"name": "before_migration",
"description": "State before database migration",
"include_namespaces": ["settings", "cache"]
}
---
#### checkpoint_restore
Restore state from a checkpoint.
`json`
{
"name": "before_migration",
"namespaces": ["settings"]
}
---
Tools for debugging and performance measurement.
#### debug_log
Log debug messages with context.
`json`
{
"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.
`json`
{
"name": "api_call",
"description": "External API request"
}
---
#### debug_time_end
End a timer and get elapsed time.
`json`
{
"name": "api_call",
"log_result": true
}
Output: Timer 'api_call' completed in 1.234s
---
General utility tools.
#### app_status
Check if an app/process is running after executing a command.
`json`
{
"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
`json`
{
"port": 3000
}
Example 2: Start app and verify it's running
`json`
{
"command": "npm start &",
"port": 8080,
"timeout": 10000
}
Example 3: Check process by name
`json`
{
"process_name": "nginx"
}
Response:
`json`
{
"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.
`json`
{
"data": "{\"name\": \"John\", \"email\": \"john@example.com\"}",
"schema": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}, \"email\": {\"type\": \"string\", \"format\": \"email\"}}, \"required\": [\"name\", \"email\"]}"
}
---
#### http_request
Make HTTP requests.
`json`
{
"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.
`json`
{
"template": "Hello, {{name}}! Welcome to {{app}}.",
"variables": {"name": "John", "app": "MCP Tools"},
"strict": false
}
Output: Hello, John! Welcome to MCP Tools.
---
The server uses temporary directories for persistence:
| Purpose | Location |
|---------|----------|
| State data | /tmp/mcp_state/ |/tmp/mcp_checkpoints/
| Checkpoints | |/tmp/mcp_debug.log
| Debug logs | |
---
`
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
1. Create or update a tool file in src/tools/
2. Define the tool with Zod schema:
`typescript
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:
`typescript
import { myTools } from "./tools/my-tools.js";
const allTools = {
...existingTools,
...myTools,
};
`
4. Rebuild: npm run build`
---
MIT