read_documentation

Instructions

Implementation Reference

• src/mcp_spark_documentation/server.py:89-119 (handler)

  Core implementation of the read_documentation tool. Calls get_database().get_document(path) and returns JSON-formatted document content or an error message.

  def _read_documentation_impl(path: str) -> str:
      """Core implementation of read_documentation.
  
      Args:
          path: The relative path to the documentation file.
  
      Returns:
          JSON-formatted document content or error message.
      """
      db = get_database()
      document = db.get_document(path)
  
      if not document:
          return json.dumps(
              {
                  "error": f"Document not found: {path}",
                  "suggestion": "Use search_documentation to find valid document paths.",
              }
          )
  
      return json.dumps(
          {
              "path": document.path,
              "title": document.title,
              "description": document.description,
              "section": document.section,
              "url": document.url,
              "content": document.content,
          },
          indent=2,
      )

• src/mcp_spark_documentation/server.py:145-158 (registration)

  The @mcp.tool() decorator registers read_documentation as an MCP tool. The function accepts a path string and delegates to _read_documentation_impl.

  @mcp.tool()
  def read_documentation(path: str) -> str:
      """Read the full content of a specific Spark documentation page.
  
      Args:
          path: The relative path to the documentation file (e.g.,
                'sql-ref/sql-syntax.md' or 'api/python/index.md'). This path
                is returned in search results.
  
      Returns:
          The full markdown content of the documentation page, or an error
          message if the page is not found.
      """
      return _read_documentation_impl(path)

• src/mcp_spark_documentation/database.py:155-179 (helper)

  Database helper get_document(path) called by the handler. Queries the SQLite 'documents' table by path and returns a Document dataclass or None.

  def get_document(self, path: str) -> Document | None:
      """Retrieve a document by path.
  
      Args:
          path: Relative path to the document.
  
      Returns:
          Document instance or None if not found.
      """
      with self._get_connection() as conn:
          cursor = conn.execute(
              "SELECT * FROM documents WHERE path = ?",
              (path,),
          )
          row = cursor.fetchone()
          if row:
              return Document(
                  path=row["path"],
                  title=row["title"],
                  description=row["description"],
                  section=row["section"],
                  content=row["content"],
                  url=row["url"],
              )
          return None

• src/mcp_spark_documentation/models.py:15-24 (schema)

  The Document dataclass model used to represent the documentation content returned by read_documentation.

  @dataclass
  class Document:
      """Represents a documentation page."""
  
      path: str
      title: str
      description: str | None
      section: str
      content: str
      url: str