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