Vibe Math MCP

Instructions

Implementation Reference

• src/vibe_math_mcp/tools/linalg.py:181-211 (registration)

  Registers the matrix_decomposition tool with the MCP server, providing detailed description and annotations.

  @mcp.tool(
      name="matrix_decomposition",
      description="""Matrix decompositions: eigenvalues/vectors, SVD, QR, Cholesky, LU.
  
  Examples:
  
  EIGENVALUE DECOMPOSITION:
      matrix=[[4,2],[1,3]], decomposition="eigen"
      Result: {eigenvalues: [5, 2], eigenvectors: [[0.89,0.45],[0.71,-0.71]]}
  
  SINGULAR VALUE DECOMPOSITION (SVD):
      matrix=[[1,2],[3,4],[5,6]], decomposition="svd"
      Result: {U: 3×3, singular_values: [9.5, 0.77], Vt: 2×2}
  
  QR FACTORISATION:
      matrix=[[1,2],[3,4]], decomposition="qr"
      Result: {Q: orthogonal, R: upper triangular}
  
  CHOLESKY (symmetric positive definite):
      matrix=[[4,2],[2,3]], decomposition="cholesky"
      Result: {L: [[2,0],[1,1.41]]} where A=LL^T
  
  LU DECOMPOSITION:
      matrix=[[2,1],[4,3]], decomposition="lu"
      Result: {P: permutation, L: lower, U: upper} where A=PLU""",
      annotations=ToolAnnotations(
          title="Matrix Decomposition",
          readOnlyHint=True,
          idempotentHint=True,
      ),
  )

• src/vibe_math_mcp/tools/linalg.py:212-215 (schema)

  Defines the input schema with Pydantic annotations for matrix (2D list of floats) and decomposition type (enum).

  async def matrix_decomposition(
      matrix: Annotated[List[List[float]], Field(description="Matrix to decompose as 2D nested list (e.g., [[4,2],[1,3]])")],
      decomposition: Annotated[Literal["eigen", "svd", "qr", "cholesky", "lu"], Field(description="Decomposition type: eigen=eigenvalues/vectors, svd=singular value, qr=QR, cholesky=symmetric positive definite, lu=LU factorisation")],
  ) -> str:

• src/vibe_math_mcp/tools/linalg.py:216-298 (handler)

  Executes the matrix decomposition using SciPy.linalg functions (eig, svd, qr, cholesky, lu), handles validation, converts formats, and returns formatted JSON results.

  """Matrix decompositions using SciPy: eigen (λ,v), SVD (UΣV^T), QR (orthogonal×triangular), Cholesky (LL^T), LU (PLU). For analysis, solving, and numerical stability."""
  try:
      mat = list_to_numpy(matrix)
  
      if decomposition == "eigen":
          if mat.shape[0] != mat.shape[1]:
              raise ValueError(
                  f"Eigenvalue decomposition requires square matrix. Got shape: {mat.shape}"
              )
  
          eigenvalues: NDArray[np.complexfloating]
          eigenvectors: NDArray[np.complexfloating]
          eigenvalues, eigenvectors = la.eig(mat)  # type: ignore[misc]
  
          return format_result(
              {
                  "eigenvalues": eigenvalues.tolist(),
                  "eigenvectors": eigenvectors.tolist(),
              },
              {"decomposition": decomposition}
          )
  
      elif decomposition == "svd":
          U, s, Vt = la.svd(mat)
  
          return format_result(
              {
                  "U": U.tolist(),
                  "singular_values": s.tolist(),
                  "Vt": Vt.tolist(),
              },
              {"decomposition": decomposition}
          )
  
      elif decomposition == "qr":
          Q: NDArray[np.floating]
          R: NDArray[np.floating]
          Q, R = la.qr(mat)  # type: ignore[misc]
  
          return format_result(
              {"Q": Q.tolist(), "R": R.tolist()},
              {"decomposition": decomposition}
          )
  
      elif decomposition == "cholesky":
          if mat.shape[0] != mat.shape[1]:
              raise ValueError(
                  f"Cholesky decomposition requires square matrix. Got shape: {mat.shape}"
              )
  
          # Check if matrix is symmetric
          if not np.allclose(mat, mat.T):
              raise ValueError("Cholesky decomposition requires symmetric matrix")
  
          try:
              L = la.cholesky(mat, lower=True)
              return format_result(
                  {"L": L.tolist()},
                  {"decomposition": decomposition, "note": "A = L * L^T"}
              )
          except np.linalg.LinAlgError:
              raise ValueError("Matrix is not positive definite")
  
      elif decomposition == "lu":
          P, L, U = la.lu(mat)  # type: ignore[misc]
  
          return format_result(
              {
                  "P": P.tolist(),
                  "L": L.tolist(),
                  "U": U.tolist(),
              },
              {"decomposition": decomposition, "note": "A = P * L * U"}
          )
  
      else:
          raise ValueError(f"Unknown decomposition: {decomposition}")
  
  except Exception as e:
      if isinstance(e, ValueError):
          raise
      raise ValueError(f"Matrix decomposition failed: {str(e)}")