Interactive MCP Explorer

Real-Time Model Context Protocol Server & Client Dashboard

An interactive Model Context Protocol (MCP) server and client environment. It enables seamless integration of a custom user database server with a Groq-powered LLM client. Using standard MCP transports, the client exposes resources, triggers prompts, and enables the model to dynamically call tools—including LLM-backed sampling loops—all via an interactive command-line interface.

---

How It Works

This project demonstrates the core aspects of the Model Context Protocol (MCP), connecting a custom server that exposes database endpoints to a client that orchestrates LLM queries and manual protocol actions.

┌─────────────────────────────────────────────────────────────────────┐
│                       MCP CLIENT ARCHITECTURE                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   User Input (CLI Menu via Inquirer)                                │
│        │                                                            │
│        ├───────▶ [Query] ──▶ Groq Llama-3.3-70b (via AI SDK)        │
│        │                       │                                    │
│        │                       ▼                                    │
│        │                 Dynamic Tools Auto-Execution               │
│        │                                                            │
│        ├───────▶ [Tools] ──▶ Manual Tool Call Parameter Input       │
│        │                                                            │
│        ├───────▶ [Prompts] ─▶ Run Server-side Prompt Templates      │
│        │                                                            │
│        └───────▶ [Resources] ▶ Read Static & Dynamic URIs           │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
                               │   ▲
                  Stdio Server │   │ Stdio Client
                     Transport │   │ Transport
                               ▼   │
┌─────────────────────────────────────────────────────────────────────┐
│                       MCP SERVER ARCHITECTURE                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   MCP Resources & Tools Registry                                    │
│        │                                                            │
│        ├─ Resource [users:/all] ──▶ Fetch Database (user.json)      │
│        ├─ Resource [users://{id}] ─▶ Fetch Specific User            │
│        │                                                            │
│        ├─ Tool [create-user] ─────▶ Write to JSON Database          │
│        ├─ Tool [create-user-from-name] ──┐                          │
│        │                                 │ (MCP Sampling Request)   │
│        └─ Tool [create-random-user] ─────▼                          │
│                [Client LLM Sampling Loop] ──▶ Fill Profile Details   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key Features

• Interactive CLI Dashboard — A terminal menu interface built with Inquirer.js allowing users to manually invoke MCP Tools, fetch Resources, resolve Prompts, or run AI Queries.
• Dynamic Tool Calling — The client maps registered MCP tools directly to the Vercel AI SDK, allowing Groq's Llama-3.3-70b model to intelligently decide when and how to call tools in response to natural language queries.
• Bi-directional LLM Sampling — Supports MCP client-side sampling. When the server needs to create a user profile given only a name (or randomly), it requests LLM assistance back from the client (sampling/createMessage), which the client fulfills using Groq.
• Resource Templates — Implements static and dynamic resource resolution patterns (users:/all and users://{userId}/profile) to surface structured JSON database content to the LLM or user.
• Persistent File DB — Includes a lightweight JSON database with helpers to read and write records securely with TypeScript and Node fs APIs.

Tech Stack

Layer	Technology	Purpose
MCP Protocol	@modelcontextprotocol/sdk	Core SDK for server registration and client connection orchestration
LLM Provider	@ai-sdk/groq	Interfaces with Groq API using high-performance llama-3.3-70b-versatile
AI SDK	ai (Vercel)	Orchestrates tool-calling loop and text generation
Frontend/CLI	@inquirer/prompts	Renders clean interactive selectors, inputs, and confirmations
Runtime/Bundling	tsx & typescript	Runs ESModules directly and compiles TS files with source-map support
Development Tools	@modelcontextprotocol/inspector	Visual inspection tool to inspect and debug MCP tools, resources, and prompts

Project Structure

.
├── src/
│   ├── client.ts             # Interactive Inquirer CLI & Groq LLM Client
│   ├── server.ts             # MCP Server registering tools, prompts, & resources
│   ├── server.d.ts           # Type declarations for server module
│   └── data/
│       └── user.json         # Mock database storing user profile records
│
├── build/                    # Compiled JavaScript build assets
├── .vscode/
│   └── mcp.json              # VSCode MCP configurations for development
│
├── package.json              # Script runners and npm dependencies
├── tsconfig.json             # TypeScript compiler settings
├── .env                      # API keys and environment variables
└── .gitignore                # File exclusions for version control

Getting Started

Prerequisites

• Node.js 20+
• npm or pnpm

Installation

# Clone the repository
git clone https://github.com/your-username/mcp-server-and-client.git
cd mcp-server-and-client

# Install dependencies
npm install

Environment Setup

Create a .env file in the root directory:

GROQ_API_KEY=your_groq_api_key_here

Running the Project

1. Start the Interactive CLI Client

The client connects to the server and presents a CLI dashboard:

npm run client:dev

2. Run the MCP Server directly (optional)

To run the server standalone on stdio:

npm run server:dev

3. Inspect the Server via MCP Inspector

To interactively debug the server resources, tools, and prompts using the web inspector:

npm run server:inspect

How the MCP Pipeline Works

1. Resource Access & Templates

The Server registers:

• users:/all to fetch all user records.
• users://{userId}/profile as a Resource Template. When the client reads this URI, the server extracts userId, searches user.json, and returns the matching user metadata.

2. Client-Assisted Sampling

When create-user-from-name or create-random-user tools are called:

1. The Server sends a sampling/createMessage request to the Client.
2. The Client receives the prompt, invokes Groq to generate a realistic JSON containing fake profile details (email, address, phone number), and sends the response back to the Server.
3. The Server parses the generated content and inserts it into user.json.

3. LLM Query Interface

In the Query mode, the client configures a Vercel AI SDK text generation model, exposing all MCP server tools directly to the model. When you ask "add a user named Vedant with email vedant@example.com", the LLM determines that it should invoke the create-user tool and executes it automatically.

Customization

• Data Schema — Modify src/data/user.json or customize target schema objects in src/server.ts to represent other domains (e.g. products, devices, inventory).
• LLM Settings — Switch models or customize system prompts inside src/client.ts to adjust temperature, token limit, or model characteristics.
• Transports — Currently using stdio transport. You can easily adapt the setup to use SSE (Server-Sent Events) for remote network connections.

Acknowledgments

• Model Context Protocol (Anthropic) for the standard specification.
• Vercel AI SDK for the universal tool execution layer.
• Groq for high-performance open-weight model hosting.
• Inquirer.js for the rich terminal CLI selectors.