Linux MCP Server

Instructions

Implementation Reference

• src/linux_mcp/tools/__init__.py:161-175 (handler)

  The core implementation of the file_read tool logic, including security checks for path traversal.

  def execute_file_read(path: str) -> str:
      """Read a file and return its contents."""
      tool = get_tool_by_name("file_read")
      tool_id = next(tid for tid, t in {}.items() if t.name == "file_read")  # placeholder
  
      # Security: path traversal check
      resolved = Path(path).resolve()
      if not str(resolved).startswith(os.path.expanduser("~")):
          log_action(tool_id or "unknown", {"path": path}, "BLOCKED: outside home", False)
          return "Error: Can only read files within home directory"
  
      try:
          content = resolved.read_text()
          log_action(tool_id or "unknown", {"path": path}, "OK", True)
          return content

• src/linux_mcp/mcp/__init__.py:51-57 (handler)

  The MCP handler function that processes tool calls and invokes the execute_file_read helper.

  async def handle_file_read(arguments: dict[str, Any]) -> list[TextContent]:
      """Handle file_read tool calls."""
      if not arguments or "path" not in arguments:
          return [TextContent(type="text", text="Error: missing 'path' parameter")]
  
      result = execute_file_read(arguments["path"])
      return [TextContent(type="text", text=result)]

• src/linux_mcp/tools/__init__.py:24-35 (registration)

  Tool registration including schema definitions for file_read.

  register_tool(
      name="file_read",
      scope=PermissionLevel.SAFE,
      description="Read contents of a file",
      params_schema={
          "type": "object",
          "properties": {
              "path": {"type": "string", "description": "Absolute path to file"},
          },
          "required": ["path"],
      },
  )