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)

bash

# 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

bash

# ✅ 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

bash

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:

bash

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

List Resources:

bash

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

List Prompts:

bash

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

Call Tool (No Parameters)

bash

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

Call Tool (With Parameters)

bash

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

Multiple Parameters:

bash

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

Read Resource

bash

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

Get Prompt (Currently Broken)

bash

# 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

bash

# 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

bash

# 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

bash

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

bash

#!/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:

bash

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

json

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

Valid Multi-Content Response

json

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

Valid Resource Response

json

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

Examples

Example 1: Basic Tool Test

bash

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

bash

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

bash

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

Example 4: Full Server Validation

bash

# 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

•Always resolve dependencies first: Run Pkg.resolve() and Pkg.precompile()
•Work from project root: Not from subdirectories
•
Use correct flags:
- •--tool-arg for tool parameters (repeatable)
- •--prompt-args for prompt parameters (plural, repeatable)
- •--uri for resource URIs
•
Test systematically:
- •List all components first
- •Test each individually
- •Validate responses
•Account for Julia JIT: First request takes 5-10 seconds
•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

bash

# 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:

bash

# 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

bash

# 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