Update docs with jsonrpc tutorial

[crivetimihai]

PR: Enhanced MCP JSON-RPC Documentation

Closes #19 Closes #323

Overview

This PR implements comprehensive developer guides for using MCP (Model Context Protocol) via raw JSON-RPC commands, addressing issues #19 and #323.

Changes Made

1. Enhanced Fast-Time-Server Documentation (Issue #323)

File: docs/docs/using/servers/go-fast-time-server.md

Added a new "Developer Guide: Raw JSON-RPC Protocol Usage" section with:

• Complete JSON-RPC over HTTP examples

  • Full session script showing complete MCP protocol flow
  • Individual command examples for all MCP operations
  • Authentication examples with Bearer tokens

• STDIO protocol examples

  • Interactive testing methods
  • Script-based testing examples
  • Here-document usage patterns

• Expected response formats

  • Successful initialize responses
  • Tools list responses
  • Tool call responses
  • Error response examples

• Comprehensive troubleshooting

  • JSON-RPC specific issues and solutions
  • Authentication error handling
  • STDIO mode troubleshooting
  • Connection and format validation

• Integration examples

  • Production-ready Python client implementation
  • Node.js client implementation
  • Practical usage patterns

2. New MCP JSON-RPC Developer Guide (Issue #19)

File: docs/docs/development/mcp-developer-guide-json-rpc.md (NEW)

Created comprehensive guide covering:

• Complete MCP protocol documentation

  • Protocol initialization sequence
  • Authentication setup and token management
  • Multiple transport methods (HTTP JSON-RPC, SSE, STDIO)

• Working with MCP components

  • Tools (list, call, error handling)
  • Resources (list, read)
  • Prompts (list, get with arguments)

• Transport-specific examples

  • HTTP JSON-RPC with complete session flows
  • Server-Sent Events (SSE) for real-time communication
  • STDIO for desktop client integration

• Error handling and troubleshooting

  • Standard JSON-RPC error codes
  • MCP Gateway specific issues
  • Known bugs and workarounds (e.g., initialize method async issue)

• Production-ready integration examples

  • Full Python client implementation with proper error handling
  • Node.js client implementation with async/await patterns
  • Best practices for session management and authentication

3. Documentation Structure Updates

Files: Multiple .pages files updated

• Moved MCP developer guide from docs/docs/using/ to docs/docs/development/ for better organization
• Updated navigation structure to include the guide in the development section
• Comprehensive navigation audit - added missing files to navigation across all documentation sections

Technical Details

Authentication Implementation

Both guides include comprehensive authentication examples:

# Token generation
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin --exp 10080 --secret my-test-key)

# Usage in requests
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:4444/rpc

Complete Session Examples

Both guides provide complete, executable session scripts:

• Fast-time-server: Complete MCP JSON-RPC session with the Go-based time server
• MCP Gateway: Full session examples for both HTTP and SSE transports

Error Handling

Comprehensive error handling coverage including:

• Standard JSON-RPC 2.0 error codes (-32700 to -32603)
• MCP Gateway specific errors (-32000 to -32099)
• Authentication and connection troubleshooting
• Known issues and their workarounds

Integration Examples

Production-ready client implementations in both Python and Node.js with:

• Proper session management
• Error handling and retry logic
• Authentication token management
• Type hints and documentation

Navigation and Organization Updates

Files Added to Navigation

The following files were missing from their respective .pages navigation and have been added:

/docs/docs/using/.pages:

• ✅ Added multi-auth-headers.md

/docs/docs/manage/.pages:

• ✅ Added export-import.md
• ✅ Added export-import-tutorial.md
• ✅ Added export-import-reference.md
• ✅ Added observability.md
• ✅ Added proxy.md
• ✅ Added well-known-uris.md

/docs/docs/deployment/.pages:

• ✅ Added proxy-auth.md

/docs/docs/overview/.pages:

• ✅ Added passthrough.md

/docs/docs/architecture/.pages:

• ✅ Added export-import-architecture.md

/docs/docs/testing/.pages:

• ✅ Added fuzzing.md

/docs/docs/development/.pages:

• ✅ Added mcp-developer-guide-json-rpc.md

File Relocation

• Moved: mcp-developer-guide-json-rpc.md from using/ to development/ section for better thematic organization
• Updated: All navigation references to reflect the new location

Benefits

1. Developer Onboarding: Comprehensive guides for understanding MCP protocol at a low level
2. Debugging Support: Complete examples for testing and debugging MCP implementations
3. Integration Reference: Production-ready client code examples
4. Protocol Compliance: Proper MCP protocol flow documentation
5. Troubleshooting: Comprehensive error handling and known issues documentation
6. Complete Navigation: All documentation files are now properly discoverable through navigation

Testing

Both guides include:

• Complete executable examples that can be copy-pasted and run
• Step-by-step testing procedures
• Expected response formats for verification
• Troubleshooting steps for common issues

Documentation Quality

• Comprehensive: Covers all aspects of MCP JSON-RPC usage
• Practical: Includes working examples and complete session flows
• Educational: Explains the protocol flow and best practices
• Production-ready: Includes proper error handling and authentication
• Maintainable: Well-structured with clear sections and examples

Related Issues

• Closes [Docs]: Add Developer Guide for using MCP via the CLI (curl commands, JSON-RPC) #19: [Docs]: Add Developer Guide for using MCP via the CLI (curl commands, JSON-RPC)
• Closes [Docs]: Add Developer Guide for using fast-time-server via JSON-RPC commands using curl or stdio #323: [Docs]: Add Developer Guide for using fast-time-server via JSON-RPC commands using curl or stdio

Future Enhancements

These guides provide a foundation for:

• Additional MCP server documentation
• Client library development
• Protocol testing and validation tools
• Integration with CI/CD pipelines for MCP testing