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.

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

Issue	Solution
Connection refused	Ensure your MCP server is running with npm run dev
"Cannot connect" error	Check that the server command is correct and the port is not in use
No tools visible	Verify your server is properly exporting tools in src/server.ts
Timeout errors	Increase the timeout in inspector settings or check server logs

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

Technology	Purpose
TypeScript	Type-safe JavaScript development
Model Context Protocol SDK	Protocol implementation for AI model communication
Playwright	Browser automation and web scraping
Zod	Runtime schema validation
tsx	TypeScript execution without build step
MCP Inspector	Web interface for testing and debugging MCP servers

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.