plp-mcpserver

PhoneLCDParts MCP Server

This project provides a Model Context Protocol (MCP) server with a tool to scrape product search results from phonelcdparts.com.

Purpose

The primary tool, scrape_phonelcdparts, allows an MCP-compatible client (like an LLM agent) to query the phonelcdparts.com website for products based on a search term. It returns structured JSON data containing the product name, price, direct URL, and image URL.

This enables automated product information retrieval for various applications, such as price tracking, data analysis, or integration into larger AI-driven workflows.

Prerequisites

• Python 3.12 or higher.
• uv (for environment and package management).
• A valid Firecrawl API key (from firecrawl.dev).

Setup

1. Clone the repository (if applicable) or navigate to the project directory:

   cd path/to/phonelcdpart-mcp
   

2. Create and activate a virtual environment using uv:

   uv venv
   source .venv/bin/activate
   

3. Configure Firecrawl API Key: Create a file named .env in the phonelcdpart-mcp project root directory (i.e., phonelcdpart-mcp/.env). Add your Firecrawl API key to this file:

   FIRECRAWL_API_KEY="YOUR_ACTUAL_FIRECRAWL_API_KEY_HERE"
   

   The application uses the python-dotenv library to load this key at runtime.

4. Install dependencies using uv:

   uv pip install .
   

   This will install all dependencies listed in pyproject.toml, including python-dotenv.

Running the MCP Server

You have a few options to run the server:

1. Directly using Python (for simple development):

   python app.py
   

2. Using Uvicorn (recommended for development, provides auto-reload): Ensure uvicorn is installed (it's in pyproject.toml).

   uvicorn app:mcp --reload --host 0.0.0.0 --port 8000
   

   (The app:mcp refers to the mcp instance of FastMCP in your app.py file.)

3. Using the installed script (if uv pip install . was successful): After a successful uv pip install ., a script defined in pyproject.toml should be available:

   start-mcp
   

   This will typically use the mcp.run() method.

The server will usually start on http://127.0.0.1:8000 or http://0.0.0.0:8000.

Using the Tool

Once the server is running, you can interact with it using any MCP-compatible client.

• Tool Name: scrape_phonelcdparts
• Description (from docstring): Scrapes product information (name, price, URL, image URL) from phonelcdparts.com for a given search query.
• Argument:
  • search_query (string): The product search term (e.g., "iphone 15 pro max lcd").
• Returns: A list of dictionaries, where each dictionary contains:
  • name (string)
  • price (string)
  • url (string)
  • image_url (string)

Example Call (conceptual, using a Python client):

# (This is a conceptual example of how a client might call the tool)
# import asyncio
# from fastmcp import Client
#
# async def main():
#     # Ensure the server_url matches where your MCP server is running
#     server_url = "http://127.0.0.1:8000/sse" 
#     async with Client(server_url) as client:
#         try:
#             result = await client.call_tool(
#                 "scrape_phonelcdparts", 
#                 {"search_query": "iphone 14 screen"}
#             )
#             if result and result.data:
#                 print("Tool Result:")
#                 for item in result.data:
#                     print(item)
#             else:
#                 print("No data returned or tool call failed.")
#         except Exception as e:
#             print(f"Error calling tool: {e}")
#
# if __name__ == "__main__":
#     asyncio.run(main())

This client code would connect to your running MCP server and invoke the scrape_phonelcdparts tool with the specified search query, then print the structured JSON results.