Skip to content

README.md

Latest commit

 

History

History
450 lines (318 loc) · 27.9 KB

README.md

File metadata and controls

450 lines (318 loc) · 27.9 KB

Μάθημα: Δημιουργία ενός MCP Server για Αναζήτηση στο Web

Αυτό το κεφάλαιο δείχνει πώς να φτιάξετε έναν πραγματικό AI agent που ενσωματώνεται με εξωτερικά APIs, διαχειρίζεται διάφορους τύπους δεδομένων, χειρίζεται σφάλματα και οργανώνει πολλά εργαλεία—όλα σε μορφή έτοιμη για παραγωγή. Θα δείτε:

  • Ενσωμάτωση με εξωτερικά APIs που απαιτούν αυθεντικοποίηση
  • Διαχείριση διαφορετικών τύπων δεδομένων από πολλαπλά endpoints
  • Αξιόπιστη διαχείριση σφαλμάτων και στρατηγικές καταγραφής
  • Οργάνωση πολλαπλών εργαλείων σε έναν server

Στο τέλος, θα έχετε πρακτική εμπειρία με πρότυπα και βέλτιστες πρακτικές απαραίτητες για προχωρημένες εφαρμογές AI και LLM.

Εισαγωγή

Σε αυτό το μάθημα θα μάθετε πώς να δημιουργήσετε έναν προηγμένο MCP server και client που επεκτείνει τις δυνατότητες LLM με δεδομένα web σε πραγματικό χρόνο χρησιμοποιώντας το SerpAPI. Αυτή είναι μια κρίσιμη δεξιότητα για την ανάπτυξη δυναμικών AI agents που έχουν πρόσβαση σε ενημερωμένες πληροφορίες από το διαδίκτυο.

Στόχοι Μάθησης

Στο τέλος αυτού του μαθήματος, θα μπορείτε να:

  • Ενσωματώνετε εξωτερικά APIs (όπως το SerpAPI) με ασφάλεια σε έναν MCP server
  • Υλοποιείτε πολλαπλά εργαλεία για αναζήτηση στο web, ειδήσεις, προϊόντα και Q&A
  • Αναλύετε και μορφοποιείτε δομημένα δεδομένα για κατανάλωση από LLM
  • Διαχειρίζεστε σφάλματα και περιορισμούς ρυθμού API αποτελεσματικά
  • Δημιουργείτε και δοκιμάζετε τόσο αυτοματοποιημένους όσο και διαδραστικούς MCP clients

Web Search MCP Server

Αυτή η ενότητα παρουσιάζει την αρχιτεκτονική και τα χαρακτηριστικά του Web Search MCP Server. Θα δείτε πώς το FastMCP και το SerpAPI χρησιμοποιούνται μαζί για να επεκτείνουν τις δυνατότητες LLM με δεδομένα web σε πραγματικό χρόνο.

Επισκόπηση

Αυτή η υλοποίηση περιλαμβάνει τέσσερα εργαλεία που δείχνουν την ικανότητα του MCP να χειρίζεται διάφορες, εξωτερικές API-driven εργασίες με ασφάλεια και αποδοτικότητα:

  • general_search: Για ευρείες αποτελέσματα web
  • news_search: Για πρόσφατους τίτλους ειδήσεων
  • product_search: Για δεδομένα ηλεκτρονικού εμπορίου
  • qna: Για αποσπάσματα ερωτήσεων και απαντήσεων

Χαρακτηριστικά

  • Παραδείγματα Κώδικα: Περιλαμβάνει blocks κώδικα για Python (και εύκολη επέκταση σε άλλες γλώσσες) με αναδιπλούμενες ενότητες για μεγαλύτερη σαφήνεια
Python 
# Example usage of the general_search tool
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("general_search", arguments={"query": "open source LLMs"})
            print(result)

Πριν τρέξετε τον client, είναι χρήσιμο να καταλάβετε τι κάνει ο server. Το server.py file implements the MCP server, exposing tools for web, news, product search, and Q&A by integrating with SerpAPI. It handles incoming requests, manages API calls, parses responses, and returns structured results to the client.

You can review the full implementation in server.py.

Εδώ ένα σύντομο παράδειγμα για το πώς ο server ορίζει και καταχωρεί ένα εργαλείο:

Python Server 
# server.py (excerpt)
from mcp.server import MCPServer, Tool

async def general_search(query: str):
    # ...implementation...

server = MCPServer()
server.add_tool(Tool("general_search", general_search))

if __name__ == "__main__":
    server.run()
  • Ενσωμάτωση Εξωτερικού API: Δείχνει ασφαλή διαχείριση κλειδιών API και εξωτερικών αιτημάτων
  • Ανάλυση Δομημένων Δεδομένων: Δείχνει πώς να μετατρέπετε τις απαντήσεις API σε μορφές φιλικές προς LLM
  • Διαχείριση Σφαλμάτων: Αξιόπιστη διαχείριση σφαλμάτων με κατάλληλη καταγραφή
  • Διαδραστικός Client: Περιλαμβάνει αυτοματοποιημένες δοκιμές και διαδραστική λειτουργία για δοκιμές
  • Διαχείριση Συμφραζομένων: Χρησιμοποιεί MCP Context για καταγραφή και παρακολούθηση αιτημάτων

Προαπαιτούμενα

Πριν ξεκινήσετε, βεβαιωθείτε ότι το περιβάλλον σας έχει ρυθμιστεί σωστά ακολουθώντας τα παρακάτω βήματα. Αυτό θα διασφαλίσει ότι όλες οι εξαρτήσεις είναι εγκατεστημένες και τα API keys σας έχουν ρυθμιστεί σωστά για ομαλή ανάπτυξη και δοκιμές.

  • Python 3.8 ή νεότερη
  • Κλειδί SerpAPI (Κάντε εγγραφή στο SerpAPI - υπάρχει δωρεάν πακέτο)

Εγκατάσταση

Για να ξεκινήσετε, ακολουθήστε τα παρακάτω βήματα για να ρυθμίσετε το περιβάλλον σας:

  1. Εγκαταστήστε τις εξαρτήσεις χρησιμοποιώντας uv (προτεινόμενο) ή pip:
# Using uv (recommended)
uv pip install -r requirements.txt

# Using pip
pip install -r requirements.txt
  1. Δημιουργήστε ένα αρχείο .env στη ρίζα του έργου με το κλειδί SerpAPI σας:
SERPAPI_KEY=your_serpapi_key_here

Χρήση

Ο Web Search MCP Server είναι το βασικό συστατικό που εκθέτει εργαλεία για αναζήτηση στο web, ειδήσεις, προϊόντα και Q&A μέσω ενσωμάτωσης με το SerpAPI. Διαχειρίζεται εισερχόμενα αιτήματα, διαχειρίζεται κλήσεις API, αναλύει απαντήσεις και επιστρέφει δομημένα αποτελέσματα στον client.

Μπορείτε να δείτε την πλήρη υλοποίηση στο server.py.

Εκκίνηση του Server

Για να ξεκινήσετε τον MCP server, χρησιμοποιήστε την παρακάτω εντολή:

python server.py

Ο server θα τρέξει ως stdio-based MCP server που ο client μπορεί να συνδεθεί απευθείας.

Λειτουργίες Client

Ο client (client.py) supports two modes for interacting with the MCP server:

  • Normal mode: Runs automated tests that exercise all the tools and verify their responses. This is useful for quickly checking that the server and tools are working as expected.
  • Interactive mode: Starts a menu-driven interface where you can manually select and call tools, enter custom queries, and see results in real time. This is ideal for exploring the server's capabilities and experimenting with different inputs.

You can review the full implementation in client.py.

Εκτέλεση του Client

Για να τρέξετε τις αυτοματοποιημένες δοκιμές (αυτό θα ξεκινήσει αυτόματα τον server):

python client.py

Ή εκτελέστε σε διαδραστική λειτουργία:

python client.py --interactive

Δοκιμές με Διάφορους Τρόπους

Υπάρχουν αρκετοί τρόποι να δοκιμάσετε και να αλληλεπιδράσετε με τα εργαλεία που παρέχει ο server, ανάλογα με τις ανάγκες και τη ροή εργασίας σας.

Δημιουργία Προσαρμοσμένων Σκριπτών Δοκιμών με το MCP Python SDK

Μπορείτε επίσης να φτιάξετε τα δικά σας σκριπτάκια δοκιμών χρησιμοποιώντας το MCP Python SDK:

Python 
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_custom_query():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            # Call tools with your custom parameters
            result = await session.call_tool("general_search", 
                                           arguments={"query": "your custom query"})
            # Process the result

Σε αυτό το πλαίσιο, ένα "σκριπτ δοκιμών" σημαίνει ένα προσαρμοσμένο πρόγραμμα Python που γράφετε για να λειτουργεί ως client για τον MCP server. Αντί να είναι επίσημο unit test, αυτό το σκριπτ σας επιτρέπει να συνδεθείτε προγραμματιστικά στον server, να καλέσετε οποιοδήποτε από τα εργαλεία του με παραμέτρους που επιλέγετε και να ελέγξετε τα αποτελέσματα. Αυτή η προσέγγιση είναι χρήσιμη για:

  • Πρωτοτυποποίηση και πειραματισμό με κλήσεις εργαλείων
  • Επικύρωση της απόκρισης του server σε διαφορετικές εισόδους
  • Αυτοματοποίηση επαναλαμβανόμενων κλήσεων εργαλείων
  • Δημιουργία δικών σας ροών εργασίας ή ενσωματώσεων πάνω από τον MCP server

Μπορείτε να χρησιμοποιήσετε σκριπτάκια δοκιμών για να δοκιμάσετε γρήγορα νέες ερωτήσεις, να εντοπίσετε σφάλματα στη συμπεριφορά εργαλείων ή ακόμα και ως αφετηρία για πιο προχωρημένη αυτοματοποίηση. Παρακάτω είναι ένα παράδειγμα για το πώς να χρησιμοποιήσετε το MCP Python SDK για να δημιουργήσετε ένα τέτοιο σκριπτ:

Περιγραφές Εργαλείων

Μπορείτε να χρησιμοποιήσετε τα παρακάτω εργαλεία που παρέχει ο server για να εκτελέσετε διάφορους τύπους αναζητήσεων και ερωτημάτων. Κάθε εργαλείο περιγράφεται παρακάτω με τις παραμέτρους και παραδείγματα χρήσης.

Αυτή η ενότητα παρέχει λεπτομέρειες για κάθε διαθέσιμο εργαλείο και τις παραμέτρους του.

general_search

Εκτελεί μια γενική αναζήτηση στο web και επιστρέφει μορφοποιημένα αποτελέσματα.

Πώς να καλέσετε αυτό το εργαλείο:

Μπορείτε να καλέσετε το general_search από το δικό σας σκριπτ χρησιμοποιώντας το MCP Python SDK, ή διαδραστικά μέσω του Inspector ή της διαδραστικής λειτουργίας του client. Εδώ ένα παράδειγμα κώδικα με το SDK:

Παράδειγμα Python 
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_general_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("general_search", arguments={"query": "latest AI trends"})
            print(result)

Εναλλακτικά, σε διαδραστική λειτουργία, επιλέξτε general_search from the menu and enter your query when prompted.

Parameters:

  • query (string): Το ερώτημα αναζήτησης

Παράδειγμα Αιτήματος:

{
  "query": "latest AI trends"
}

news_search

Αναζητά πρόσφατα άρθρα ειδήσεων σχετικά με ένα ερώτημα.

Πώς να καλέσετε αυτό το εργαλείο:

Μπορείτε να καλέσετε το news_search από το δικό σας σκριπτ χρησιμοποιώντας το MCP Python SDK, ή διαδραστικά μέσω του Inspector ή της διαδραστικής λειτουργίας του client. Εδώ ένα παράδειγμα κώδικα με το SDK:

Παράδειγμα Python 
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_news_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("news_search", arguments={"query": "AI policy updates"})
            print(result)

Εναλλακτικά, σε διαδραστική λειτουργία, επιλέξτε news_search from the menu and enter your query when prompted.

Parameters:

  • query (string): Το ερώτημα αναζήτησης

Παράδειγμα Αιτήματος:

{
  "query": "AI policy updates"
}

product_search

Αναζητά προϊόντα που ταιριάζουν με ένα ερώτημα.

Πώς να καλέσετε αυτό το εργαλείο:

Μπορείτε να καλέσετε το product_search από το δικό σας σκριπτ χρησιμοποιώντας το MCP Python SDK, ή διαδραστικά μέσω του Inspector ή της διαδραστικής λειτουργίας του client. Εδώ ένα παράδειγμα κώδικα με το SDK:

Παράδειγμα Python 
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_product_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("product_search", arguments={"query": "best AI gadgets 2025"})
            print(result)

Εναλλακτικά, σε διαδραστική λειτουργία, επιλέξτε product_search from the menu and enter your query when prompted.

Parameters:

  • query (string): Το ερώτημα αναζήτησης προϊόντος

Παράδειγμα Αιτήματος:

{
  "query": "best AI gadgets 2025"
}

qna

Λαμβάνει άμεσες απαντήσεις σε ερωτήσεις από μηχανές αναζήτησης.

Πώς να καλέσετε αυτό το εργαλείο:

Μπορείτε να καλέσετε το qna από το δικό σας σκριπτ χρησιμοποιώντας το MCP Python SDK, ή διαδραστικά μέσω του Inspector ή της διαδραστικής λειτουργίας του client. Εδώ ένα παράδειγμα κώδικα με το SDK:

Παράδειγμα Python 
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_qna():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("qna", arguments={"question": "what is artificial intelligence"})
            print(result)

Εναλλακτικά, σε διαδραστική λειτουργία, επιλέξτε qna from the menu and enter your question when prompted.

Parameters:

  • question (string): Η ερώτηση για να βρεθεί απάντηση

Παράδειγμα Αιτήματος:

{
  "question": "what is artificial intelligence"
}

Λεπτομέρειες Κώδικα

Αυτή η ενότητα παρέχει αποσπάσματα κώδικα και αναφορές για τις υλοποιήσεις του server και του client.

Python

Δείτε το server.py and client.py για πλήρεις λεπτομέρειες υλοποίησης.

# Example snippet from server.py:
import os
import httpx
# ...existing code...

Προχωρημένες Έννοιες σε Αυτό το Μάθημα

Πριν ξεκινήσετε την κατασκευή, εδώ είναι μερικές σημαντικές προχωρημένες έννοιες που θα εμφανιστούν σε όλο το κεφάλαιο. Η κατανόησή τους θα σας βοηθήσει να ακολουθήσετε, ακόμα και αν είναι η πρώτη φορά που τις βλέπετε:

  • Οργάνωση Πολλαπλών Εργαλείων: Αυτό σημαίνει ότι τρέχετε πολλά διαφορετικά εργαλεία (όπως αναζήτηση web, ειδήσεις, προϊόντα και Q&A) μέσα σε έναν MCP server. Σας επιτρέπει να διαχειρίζεστε ποικιλία εργασιών, όχι μόνο μία.
  • Διαχείριση Περιορισμών Ρυθμού API: Πολλά εξωτερικά APIs (όπως το SerpAPI) περιορίζουν πόσα αιτήματα μπορείτε να κάνετε σε συγκεκριμένο χρόνο. Ο καλός κώδικας ελέγχει αυτούς τους περιορισμούς και τους χειρίζεται με ομαλό τρόπο, ώστε η εφαρμογή να μην σπάει αν ξεπεράσετε το όριο.
  • Ανάλυση Δομημένων Δεδομένων: Οι απαντήσεις API είναι συχνά πολύπλοκες και φωλιασμένες. Αυτή η έννοια αφορά τη μετατροπή αυτών των απαντήσεων σε καθαρές, εύχρηστες μορφές φιλικές προς LLM ή άλλα προγράμματα.
  • Ανάκτηση από Σφάλματα: Μερικές φορές κάτι πάει στραβά—ίσως το δίκτυο αποτύχει ή το API δεν επιστρέψει αυτά που περιμένετε. Η ανάκτηση από σφάλματα σημαίνει ότι ο κώδικάς σας μπορεί να χειριστεί αυτά τα προβλήματα και να δώσει χρήσιμα μηνύματα αντί να καταρρεύσει.
  • Επικύρωση Παραμέτρων: Αυτό αφορά τον έλεγχο ότι όλες οι είσοδοι στα εργαλεία σας είναι σωστές και ασφαλείς για χρήση. Περιλαμβάνει τον ορισμό προεπιλεγμένων τιμών και τη διασφάλιση ότι οι τύποι είναι σωστοί, βοηθώντας στην αποφυγή σφαλμάτων και παρεξηγήσεων.

Αυτή η ενότητα θα σας βοηθήσει να διαγνώσετε και να λύσετε κοινά προβλήματα που μπορεί να αντιμετωπίσετε κατά τη δουλειά με τον Web Search MCP Server. Αν συναντήσετε σφάλματα ή απρόβλεπτη συμπεριφορά, αυτή η ενότητα αντιμετώπισης προβλημάτων παρέχει λύσεις στα πιο συχνά ζητήματα. Διαβάστε τις συμβουλές πριν ζητήσετε περαιτέρω βοήθεια—συχνά λύνονται γρήγορα έτσι.

Αντιμετώπιση Προβλημάτων

Κατά τη δουλειά με τον Web Search MCP Server, μπορεί να συναντήσετε προβλήματα—αυτό είναι φυσιολογικό όταν αναπτύσσετε με εξωτερικά APIs και νέα εργαλεία. Αυτή η ενότητα παρέχει πρακτικές λύσεις στα πιο κοινά προβλήματα, ώστε να επιστρέψετε γρήγορα στη δουλειά. Αν αντιμετωπίσετε σφάλμα, ξεκινήστε από εδώ: οι παρακάτω συμβουλές καλύπτουν τα ζητήματα που συναντούν οι περισσότεροι χρήστες και συχνά λύνουν το πρόβλημά σας χωρίς επιπλέον βοήθεια.

Συχνά Προβλήματα

Παρακάτω είναι μερικά από τα πιο συχνά προβλήματα που αντιμετωπίζουν οι χρήστες, μαζί με σαφείς εξηγήσεις και βήματα για την επίλυσή τους:

  1. Λείπει το SERPAPI_KEY στο αρχείο .env

    • Αν δείτε το σφάλμα SERPAPI_KEY environment variable not found, it means your application can't find the API key needed to access SerpAPI. To fix this, create a file named .env in your project root (if it doesn't already exist) and add a line like SERPAPI_KEY=your_serpapi_key_here. Make sure to replace your_serpapi_key_here with your actual key from the SerpAPI website.

  2. Module not found errors

    • Errors such as ModuleNotFoundError: No module named 'httpx' indicate that a required Python package is missing. This usually happens if you haven't installed all the dependencies. To resolve this, run pip install -r requirements.txt in your terminal to install everything your project needs.

  3. Connection issues

    • If you get an error like Error during client execution, it often means the client can't connect to the server, or the server isn't running as expected. Double-check that both the client and server are compatible versions, and that server.py is present and running in the correct directory. Restarting both the server and client can also help.

  4. SerpAPI errors

    • Seeing Search API returned error status: 401 means your SerpAPI key is missing, incorrect, or expired. Go to your SerpAPI dashboard, verify your key, and update your .env, βεβαιωθείτε ότι το αρχείο .env υπάρχει και περιέχει το σωστό κλειδί. Αν το κλειδί σας είναι σωστό αλλά το σφάλμα συνεχίζει, ελέγξτε αν το δωρεάν πακέτο σας έχει εξαντληθεί.

Λειτουργία Debug

Κανονικά, η εφαρμογή καταγράφει μόνο σημαντικές πληροφορίες. Αν θέλετε να δείτε περισσότερες λεπτομέρειες για το τι συμβαίνει (π.χ. για να διαγνώσετε δύσκολα ζητήματα), μπορείτε να ενεργοποιήσετε τη λειτουργία DEBUG. Αυτό θα σας δείξει πολύ περισσότερα για κάθε βήμα που κάνει η εφαρμογή.

Παράδειγμα: Κανονική Έξοδος

2025-06-01 10:15:23,456 - __main__ - INFO - Calling general_search with params: {'query': 'open source LLMs'}
2025-06-01 10:15:24,123 - __main__ - INFO - Successfully called general_search

GENERAL_SEARCH RESULTS:
... (search results here) ...

Παράδειγμα: Έξοδος DEBUG

2025-06-01 10:15:23,456 - __main__ - INFO - Calling general_search with params: {'query': 'open source LLMs'}
2025-06-01 10:15:23,457 - httpx - DEBUG - HTTP Request: GET https://serpapi.com/search ...
2025-06-01 10:15:23,458 - httpx - DEBUG - HTTP Response: 200 OK ...
2025-06-01 10:15:24,123 - __main__ - INFO - Successfully called general_search

GENERAL_SEARCH RESULTS:
... (search results here) ...

Αποποίηση ευθυνών:
Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI Co-op Translator. Παρόλο που προσπαθούμε για ακρίβεια, παρακαλούμε να γνωρίζετε ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν σφάλματα ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του πρέπει να θεωρείται η επίσημη πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για οποιεσδήποτε παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.