NeoDB MCP Server

Instructions

Implementation Reference

• src/neodb/server.py:43-56 (registration)

  Registration of the 'get-book' tool in the list_tools handler, defining its name, description, and input schema requiring a 'book_id' parameter.

  types.Tool(
      name="get-book",
      description="Get detailed information about a specific book",
      inputSchema={
          "type": "object",
          "properties": {
              "book_id": {
                  "type": "string",
                  "description": "The ID of the book to retrieve",
              },
          },
          "required": ["book_id"],
      },
  ),

• src/neodb/server.py:197-221 (handler)

  The execution handler for the 'get-book' tool within the call_tool decorator. It retrieves the book data from the NeoDB API endpoint `/api/book/{book_id}` using the access token, formats it with format_book, and returns a TextContent response.

  elif name == "get-book":
      book_id = arguments.get("book_id")
      if not book_id:
          raise ValueError("Missing book_id parameter")
  
      async with httpx.AsyncClient() as client:
          book_data = await make_neodb_request(
              client,
              access_token,
              f"/api/book/{book_id}",
              api_base
          )
  
          if not book_data:
              return [types.TextContent(type="text", text=f"Failed to retrieve book with ID: {book_id}")]
  
          # Format detailed book information
          book_text = format_book(book_data)
          
          return [
              types.TextContent(
                  type="text",
                  text=book_text
              )
          ]

• src/neodb/server.py:91-99 (helper)

  Helper function used by the 'get-book' handler to format the retrieved book data into a readable string with title, author, rating, and description.

  def format_book(book: dict) -> str:
      """Format a book into a concise string."""
      return (
          f"Title: {book.get('title', 'Unknown')}\n"
          f"Author: {book.get('author', 'Unknown')}\n"
          f"Rating: {book.get('rating', 'N/A')}\n"
          f"Description: {book.get('description', 'No description available')}\n"
          "---"
      )

• src/neodb/server.py:59-89 (helper)

  Shared helper function used by the 'get-book' handler to make authenticated GET requests to the NeoDB API.

  async def make_neodb_request(client: httpx.AsyncClient, access_token: str, endpoint: str, api_base: str) -> dict[str, Any] | None:
      """
      Make an authenticated request to the NeoDB API
  
      Args:
          client (httpx.AsyncClient): The HTTP client to use
          access_token (str): The access token obtained from get_access_token
          endpoint (str): The API endpoint to call (e.g., '/api/me')
          api_base (str): The base URL for the NeoDB API
  
      Returns:
          dict: The API response
      """
      headers = {
          "Authorization": f"Bearer {access_token}",
          "Accept": "application/json",
      }
  
      url = f"{api_base}{endpoint}"
      
      try:
          response = await client.get(url, headers=headers, timeout=30.0)
          response.raise_for_status()
          return response.json()
      except httpx.HTTPStatusError as e:
          # Handle HTTP errors (4xx, 5xx status codes)
          return None, e.response.status_code
      except Exception as e:
          # Handle other errors (network issues, timeouts, etc)
          return None, 500  # Return 500 for internal errors