Grocery MCP - Setup & Run Instructions

Overview

Grocery MCP is a TypeScript-based Model Context Protocol (MCP) server that integrates Playwright for web automation and Zod for schema validation.

Related MCP server: PlayMCP Browser Automation Server

Prerequisites

• Node.js (v18 or higher recommended)

• npm or yarn (Node package manager)

• Git (to clone the repository)

Installation

1. Clone the Repository

git clone https://github.com/JiteshPL/grocery-mcp.git
cd grocery-mcp

2. Install Dependencies

npm install

This will install all required dependencies:

• @modelcontextprotocol/sdk - Model Context Protocol SDK

• playwright - Browser automation library

• zod - TypeScript-first schema validation

• Dev dependencies: tsx, typescript, @types/node

Running the Project

Development Mode

To run the project in development mode with auto-reload:

npm run dev

This command executes tsx src/server.ts, which starts the MCP server using the TypeScript transpiler.

Testing with MCP Inspector

Overview

MCP Inspector is a tool provided by Anthropic to test and debug MCP servers. It provides a web interface to interact with your server, inspect capabilities, and test tools.

Installation

Global Installation (Recommended)

npm install -g @modelcontextprotocol/inspector

Or Install Locally

npm install --save-dev @modelcontextprotocol/inspector

Running MCP Inspector

1. Start Your MCP Server

In one terminal window, run your server:

npm run dev

Note the server's connection details (usually stdio or a specific port if configured).

2. Launch MCP Inspector

In another terminal window:

mcp-inspector

Or if installed locally:

npx @modelcontextprotocol/inspector

3. Connect to Your Server

• The inspector will open a web interface (typically at http://localhost:5173 or similar)

• Configure the server connection:

  • Command: tsx src/server.ts

  • Transport: Select stdio (standard input/output)

• Click "Connect" to establish the connection

Testing Your MCP Server

Once connected, you can:

1. View Capabilities: See all tools and resources your server exposes

2. Inspect Schema: Review the input/output schemas for each tool

3. Execute Tools: Test individual tools with different parameters

4. View Logs: Monitor real-time server output and requests/responses

5. Debug: Check request/response payloads and error messages

Example Testing Workflow

1. Start the MCP server: npm run dev

2. Launch inspector: mcp-inspector (in another terminal)

3. Connect with command: tsx src/server.ts

4. In the inspector UI:

   • Navigate to "Tools" section

   • Select a tool to test

   • Provide test parameters

   • Click "Execute" to run the tool

   • Review the response in the inspector

Troubleshooting Inspector Connection

Project Structure

grocery-mcp/
├── src/
│   └── server.ts          # Main server entry point
├── package.json           # Project metadata and dependencies
├── tsconfig.json          # TypeScript configuration
├── README.md              # This file
└── instructions.md        # Detailed setup instructions

Key Technologies

Common Tasks

Run Server

npm run dev

Test with Inspector

# Terminal 1
npm run dev

# Terminal 2
mcp-inspector

Check TypeScript Compilation

npx tsc --noEmit

Install New Dependencies

npm install <package-name>

Troubleshooting

Port Already in Use

If the server fails to start due to a port conflict, check which process is using the port and terminate it, or modify the port in src/server.ts.

Playwright Installation Issues

If you encounter Playwright browser download issues:

npx playwright install

TypeScript Errors

Ensure you're using a compatible Node.js version:

node --version

Inspector Not Found

If mcp-inspector command is not recognized:

# Install globally
npm install -g @modelcontextprotocol/inspector

# Or use npx
npx @modelcontextprotocol/inspector

Additional Resources

• Model Context Protocol Documentation

• MCP Inspector Guide

• Playwright Documentation

• Zod Documentation

• TypeScript Documentation

Support

For issues or questions, refer to the project repository or create an issue on GitHub.