mcp-inspector

name	mcp-inspector
description	Test Model Context Protocol (MCP) servers using the MCP Inspector CLI with correct syntax

MCP Inspector Testing Skill

This skill provides comprehensive testing capabilities for Model Context Protocol (MCP) servers, particularly Julia-based servers using ModelContextProtocol.jl. It uses the correct Inspector CLI syntax verified through extensive testing.

Purpose

Test MCP servers to verify:

• Protocol compliance (2025-06-18 specification)
• Tool, resource, and prompt functionality
• Response format validation
• Error handling
• Multi-content returns

When to Use This Skill

• Testing new MCP server implementations
• Debugging MCP protocol issues
• Validating tool/resource/prompt definitions
• Verifying cross-client compatibility
• Creating test reports for MCP servers

Prerequisites

1. Resolve Dependencies (CRITICAL)

# For Julia projects - ALWAYS run these first from project root
cd /path/to/project
julia --project -e 'using Pkg; Pkg.resolve(); Pkg.precompile()'

# If examples have separate Project.toml
cd examples && julia --project -e 'using Pkg; Pkg.resolve(); Pkg.instantiate()'
cd ..

Why: Julia manifests may be resolved with different versions, causing dependency errors (especially MbedTLS_jll).

2. Work from Project Root

# ✅ CORRECT - from project root
cd /path/to/project
npx @modelcontextprotocol/inspector --cli julia --project=. examples/server.jl ...

# ❌ WRONG - from subdirectory
cd examples
npx @modelcontextprotocol/inspector --cli julia --project examples/server.jl ...
# Results in "examples/examples/server.jl: No such file" error

Correct Inspector CLI Syntax

Command Structure

npx @modelcontextprotocol/inspector --cli \
  <server-command> <server-args> \
  --method <method-name> \
  [--tool-name <name>] \
  [--tool-arg key=value ...] \
  [--uri <uri>] \
  [--prompt-name <name>] \
  [--prompt-args key=value ...]

CRITICAL: Correct Flags

Tool Arguments:

• ✅ Use --tool-arg key=value (can be repeated)
• ❌ NOT --params '{"key":"value"}'

Prompt Arguments:

• ✅ Use --prompt-args key=value (can be repeated, note plural)
• ❌ NOT --prompt-arg (singular)

Resource URI:

• ✅ Use --uri "scheme://path"

Testing stdio Servers

Basic Operations

List Tools:

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method tools/list

List Resources:

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method resources/list

List Prompts:

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method prompts/list

Call Tool (No Parameters)

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method tools/call \
  --tool-name current_time

Call Tool (With Parameters)

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/multi_content_tool.jl \
  --method tools/call \
  --tool-name flexible_response \
  --tool-arg format=text

Multiple Parameters:

--method tools/call \
--tool-name analyze \
--tool-arg param1=value1 \
--tool-arg param2=value2 \
--tool-arg param3=value3

Read Resource

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method resources/read \
  --uri "character-info://harry-potter/birthday"

Get Prompt (Currently Broken)

# This will fail due to server-side _meta bug
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method prompts/get \
  --prompt-name movie_analysis \
  --prompt-args genre="science fiction" \
  --prompt-args year=1999

Note: prompts/get currently fails due to ModelContextProtocol.jl serializing _meta: null instead of omitting the field.

Testing HTTP Servers

Start Server First

# Terminal 1: Start server
cd /path/to/project
julia --project=. examples/simple_http_server.jl

# Wait 5-10 seconds for Julia compilation

Test via mcp-remote Bridge

# Terminal 2: Test with Inspector
npx @modelcontextprotocol/inspector --cli \
  npx mcp-remote http://127.0.0.1:3000 --allow-http \
  --method tools/list

Or Test with curl

curl -X POST http://127.0.0.1:3000/ \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18"},"id":1}' \
| jq .

Standard Test Suite

Complete Server Test

#!/bin/bash
cd /path/to/project

echo "=== SETUP ==="
julia --project -e 'using Pkg; Pkg.resolve(); Pkg.precompile()'

echo -e "\n=== TOOLS/LIST ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method tools/list

echo -e "\n=== RESOURCES/LIST ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method resources/list

echo -e "\n=== PROMPTS/LIST ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method prompts/list

echo -e "\n=== TOOLS/CALL (no params) ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method tools/call \
  --tool-name current_time

echo -e "\n=== RESOURCES/READ ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method resources/read \
  --uri "character-info://harry-potter/birthday"

echo -e "\n=== TOOLS/CALL (with params) ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/multi_content_tool.jl \
  --method tools/call \
  --tool-name flexible_response \
  --tool-arg format=text

echo -e "\n=== TOOLS/CALL (multi-content) ==="
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/multi_content_tool.jl \
  --method tools/call \
  --tool-name flexible_response \
  --tool-arg format=both

Known Issues

1. ModelContextProtocol.jl _meta Field Bug

Symptom: prompts/get fails with validation error about _meta field

Cause: Server serializes _meta: null instead of omitting the field

Status: Server-side bug, NOT Inspector CLI issue

Workaround: None - needs fix in ModelContextProtocol.jl

2. EmbeddedResource Conversion Error

Symptom: Tools returning EmbeddedResource content fail with MethodError

Cause: Server cannot convert TextResourceContents to Dict for serialization

Status: Server-side bug

Workaround: Avoid EmbeddedResource content type

3. Auto-Registration (FIXED)

Previous Issue: reg_dir.jl example returned empty tool/resource/prompt lists

Cause: Julia scoping bug with names() introspection + Julia 1.12 world age semantics

Status: ✅ FIXED - Now uses include() return value instead of module introspection

Verification:

npx @modelcontextprotocol/inspector --cli julia --project=. examples/reg_dir.jl -- --method tools/list
# Returns: 3 tools (gen_2d_array, julia_version, inspect_workspace)

Component File Requirement: Component must be the last expression in the file

See: REG_DIR_BUG_ANALYSIS_AND_FIX.md for technical details

4. Julia Version Dependency Issues

Symptom: Package MbedTLS_jll is required but does not seem to be installed

Cause: Manifest resolved with different Julia version

Workaround: Run Pkg.resolve() before testing (see Prerequisites)

Response Validation

Valid Tool Response

{
  "content": [
    {
      "type": "text",
      "text": "Tool result text"
    }
  ],
  "is_error": false
}

Valid Multi-Content Response

{
  "content": [
    {
      "type": "text",
      "text": "Text content"
    },
    {
      "type": "image",
      "data": "base64data",
      "mimeType": "image/png"
    }
  ],
  "is_error": false
}

Valid Resource Response

{
  "contents": [
    {
      "uri": "scheme://path",
      "mimeType": "application/json",
      "text": "{\"data\":\"value\"}"
    }
  ]
}

Examples

Example 1: Basic Tool Test

cd /home/kalidke/julia_shared_dev/ModelContextProtocol

# Setup
julia --project -e 'using Pkg; Pkg.resolve()'

# Test
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method tools/call \
  --tool-name current_time

Example 2: Tool with Parameters

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/multi_content_tool.jl \
  --method tools/call \
  --tool-name flexible_response \
  --tool-arg format=both

Example 3: Resource Read

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method resources/read \
  --uri "character-info://harry-potter/birthday"

Example 4: Full Server Validation

# List all capabilities
npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method tools/list > tools.json

npx @modelcontextprotocol/inspector --cli \
  julia --project=. examples/time_server.jl \
  --method resources/list > resources.json

# Test each tool
jq -r '.tools[].name' tools.json | while read tool; do
  echo "Testing: $tool"
  npx @modelcontextprotocol/inspector --cli \
    julia --project=. examples/time_server.jl \
    --method tools/call \
    --tool-name "$tool"
done

# Test each resource
jq -r '.resources[].uri' resources.json | while read uri; do
  echo "Testing: $uri"
  npx @modelcontextprotocol/inspector --cli \
    julia --project=. examples/time_server.jl \
    --method resources/read \
    --uri "$uri"
done

Best Practices

1. Always resolve dependencies first: Run Pkg.resolve() and Pkg.precompile()
2. Work from project root: Not from subdirectories
3. Use correct flags:
   • --tool-arg for tool parameters (repeatable)
   • --prompt-args for prompt parameters (plural, repeatable)
   • --uri for resource URIs
4. Test systematically:
   • List all components first
   • Test each individually
   • Validate responses
5. Account for Julia JIT: First request takes 5-10 seconds
6. Check for server bugs: Some failures are server-side, not CLI issues

Performance Notes

• Julia JIT compilation: First request takes 5-10 seconds (normal)
• Subsequent requests: <100ms typically
• Inspector overhead: Minimal, <1 second per request
• HTTP server startup: Add 5-10 seconds before testing

Troubleshooting

Server Won't Start

# Check dependencies
julia --project -e 'using Pkg; Pkg.status()'

# Resolve dependencies
julia --project -e 'using Pkg; Pkg.resolve()'

# Run with full error output
julia --project examples/server.jl 2>&1 | less

Inspector Connection Closed

Check you're in the correct directory:

# Verify current directory
pwd

# Verify server file exists
ls -la examples/server.jl

# Run from project root
cd /path/to/project
npx @modelcontextprotocol/inspector --cli julia --project=. examples/server.jl ...

HTTP Port Already in Use

# Find and kill existing server
ps aux | grep "julia.*server.jl"
kill <PID>

# Or use different port in server code

Success Metrics

Based on testing with ModelContextProtocol.jl:

• ✅ tools/list: Working
• ✅ resources/list: Working
• ✅ prompts/list: Working
• ✅ tools/call (no params): Working
• ✅ tools/call (with params): Working
• ✅ resources/read: Working
• ✅ Multi-content returns: Working
• ❌ prompts/get: Broken (server bug)
• ❌ EmbeddedResource: Broken (server bug)
• ❌ Auto-registration: Broken (server bug)

Success Rate: 70% (7/10 operations working)

References

• MCP Specification: https://modelcontextprotocol.io/specification/2025-06-18/
• Inspector CLI: https://github.com/modelcontextprotocol/inspector
• Inspector Documentation: https://modelcontextprotocol.io/docs/tools/inspector
• ModelContextProtocol.jl: https://github.com/JuliaSMLM/ModelContextProtocol.jl
• Test Report: See MCP_INSPECTOR_TESTING_REPORT.md in project root