Skip to main content
Glama
Sign In
deenesjakoruzh
viktor-haag

scuffed-painter

by viktor-haag
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Scuffed Painter

一个使用 Pillow 将绘图命令渲染为栅格图像的 MCP（Model Context Protocol）服务器。它暴露两个工具：

  • draw_image — 渲染命令并将结果作为内联 PNG 图像返回。

  • draw_image_to_file — 渲染命令并将结果保存到文件。

支持五种形状，每种形状都是一个 JSON 对象，通过其 "shape" 字段区分：

shape

参数

line

start、end、color、width

rect

box（左、上、右、下）、fill、outline、width

circle

center、radius、fill、outline、width

ellipse

box（x0, y0, x1, y1）、fill、outline、width

triangle

points（恰好三个顶点）、fill、outline、width

命令按列表顺序在固定大小的白色画布上执行；后面的命令会覆盖先前的命令。颜色可以是 CSS 颜色名称或十六进制颜色代码。

安装

pip install .

这将提供 scuffed-painter 控制台脚本，它通过 stdio 启动 MCP 服务器（默认方式）。python -m scuffed_painter 是等效的替代方式。同样的命令还可以通过 HTTP（MCP Streamable HTTP 传输）运行服务器：

scuffed-painter                              # stdio transport (default)
scuffed-painter --transport http             # HTTP on 127.0.0.1:8000
scuffed-painter --transport http --host H --port P

--host 和 --port 仅适用于 HTTP 传输；默认值为 127.0.0.1 和 8000。如有必要，可以使用 --enable-cors 启用 CORS。

Related MCP server: openai-imagegen-mcp

MCP 主机配置

stdio

将服务器添加到 MCP 主机的 stdio 服务器配置中：

{
  "mcpServers": {
    "scuffed-painter": {
      "command": "scuffed-painter"
    }
  }
}

注意：在 PATH 受限的主机上，或在 virtualenv 中运行时，请改用已安装的 scuffed-painter 脚本的绝对路径（例如 which scuffed-painter 报告的路径）。

Streamable HTTP

自行启动服务器，然后将 MCP 主机指向该端点（路径为 /mcp）：

scuffed-painter --transport http --host 127.0.0.1 --port 8000
{
  "mcpServers": {
    "scuffed-painter": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

（调整键名以匹配 MCP 主机的配置格式。）

注意：使用 draw_image_to_file 时，output_path 指的是服务器运行所在的机器。通过 stdio 时，该机器与 MCP 客户端位于同一主机；当通过 HTTP 访问服务器时，该机器则是服务器所在的主机。

示例工具调用

{
  "width": 200,
  "height": 200,
  "commands": [
    {"shape": "circle", "center": [100, 80], "radius": 50, "fill": "gold", "outline": "orange", "width": 3},
    {"shape": "triangle", "points": [[50, 170], [150, 170], [100, 70]], "fill": "darkgreen"},
    {"shape": "line", "start": [20, 185], "end": [180, 185], "color": "black", "width": 2}
  ]
}

开发

仓库布局：

scuffed_painter/          the package
  server.py             server, tools, command models, rendering
  __init__.py           re-exports mcp, defines __version__
  __main__.py           python -m scuffed_painter support
  py.typed              typing marker
tests/                  pytest suite (in-process fastmcp.Client)

安装并运行测试：

pip install -e ".[dev]"
python -m pytest

Available Tools

2 tools
draw_imageA

Draws a picture with pillow and returns the resulting image as inline PNG image content. This is especially usefull for (chat) applications that can directly display images.

width: canvas width in pixels (positive integer). height: canvas height in pixels (positive integer). commands: list of drawing commands, executed in order; each command is a JSON object with a "shape" field selecting one of: line, rect, circle, ellipse, triangle.

Supported shapes and their fields: line: "shape": "line", fields: start (x, y), end (x, y), color (default black), width (default 1) rect: "shape": "rect", fields: box (left, top, right, bottom), fill (default black, None for none), outline (default None), width (default 1) circle: "shape": "circle", fields: center (x, y), radius, fill (default black, None for none), outline (default None), width (default 1) ellipse: "shape": "ellipse", fields: box (x0, y0, x1, y1), fill (default black, None for none), outline (default None), width (default 1) triangle: "shape": "triangle", fields: points (three (x, y) vertices), fill (default black, None for none), outline (default None), width (default 1)

Commands are validated individually. Invalid commands are skipped, and a warning listing them (1-based positions) is included in the result; the image still contains all valid commands in order. If no command is valid, the call fails with a listing of the per-command errors.

Coordinate system: The coordinate system has its origin at the top-left corner; x increases to the right, y increases downward. All coordinates are in pixels on a fixed-size white background canvas; drawing outside the canvas bounds is clipped (harmless). Commands run in list order, and later commands overpaint earlier ones.

Color format: Color as a CSS color name (e.g. 'red', 'darkorange') or hex code (e.g. '#8b4513'). Values are passed through to Pillow.

Paint semantics: fill=None gives an unfilled shape; outline draws the border; width is the stroke width in pixels for line/rect/circle/ellipse/triangle.

Example (200x200 canvas): { "width": 200, "height": 200, "commands": [ {"shape": "circle", "center": [100, 80], "radius": 50, "fill": "gold", "outline": "orange", "width": 3}, {"shape": "triangle", "points": [[50, 170], [150, 170], [100, 70]], "fill": "darkgreen"}, {"shape": "line", "start": [20, 185], "end": [180, 185], "color": "black", "width": 2} ] }

NameRequiredDescriptionDefault
widthYes
heightYes
commandsYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, and it delivers thoroughly. It discloses invalid-command skipping with warnings, total-invalid-command failure behavior, coordinate origin and direction, clipping, overpainting order, color formats, and pass-through to Pillow. This is far beyond what annotations alone would provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Although the description is long, the complexity of the tool justifies the length. It is well-structured with clear sections for shapes, coordinate system, colors, paint semantics, and an example, and the core purpose is front-loaded in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a highly complex nested command format, the description covers everything an agent needs: complete shape schemas, defaults, validation behavior, failure modes, coordinate system details, and a full example. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully compensates by explaining width, height, and commands in depth. It documents every supported shape, all their fields, defaults, color formats, coordinate semantics, and provides a working example, so no parameter meaning is left to inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Draws a picture with pillow and returns the resulting image as inline PNG image content.' This clearly differentiates the tool from its sibling draw_image_to_file by emphasizing inline PNG output rather than file output, so an agent can select it correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use this tool: 'especially useful for (chat) applications that can directly display images.' It does not explicitly name draw_image_to_file as the alternative for file output, but the inline-image framing strongly implies that distinction, leaving little ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

draw_image_to_fileA

Draws a picture with pillow and saves the resulting image to a file.

output_path: absolute file path to save to; the image format is inferred from the extension (e.g. .png, .jpg). Parent directories are NOT created. width: canvas width in pixels (positive integer). height: canvas height in pixels (positive integer). commands: list of drawing commands, executed in order; each command is a JSON object with a "shape" field selecting one of: line, rect, circle, ellipse, triangle.

Supported shapes and their fields: line: "shape": "line", fields: start (x, y), end (x, y), color (default black), width (default 1) rect: "shape": "rect", fields: box (left, top, right, bottom), fill (default black, None for none), outline (default None), width (default 1) circle: "shape": "circle", fields: center (x, y), radius, fill (default black, None for none), outline (default None), width (default 1) ellipse: "shape": "ellipse", fields: box (x0, y0, x1, y1), fill (default black, None for none), outline (default None), width (default 1) triangle: "shape": "triangle", fields: points (three (x, y) vertices), fill (default black, None for none), outline (default None), width (default 1)

Commands are validated individually. Invalid commands are skipped, and a warning listing them (1-based positions) is included in the result; the image still contains all valid commands in order. If no command is valid, the call fails with a listing of the per-command errors.

Coordinate system: The coordinate system has its origin at the top-left corner; x increases to the right, y increases downward. All coordinates are in pixels on a fixed-size white background canvas; drawing outside the canvas bounds is clipped (harmless). Commands run in list order, and later commands overpaint earlier ones.

Color format: Color as a CSS color name (e.g. 'red', 'darkorange') or hex code (e.g. '#8b4513'). Values are passed through to Pillow.

Paint semantics: fill=None gives an unfilled shape; outline draws the border; width is the stroke width in pixels for line/rect/circle/ellipse/triangle.

Example (200x200 canvas): { "output_path": "/home/myuser/documents/picture.png", "width": 200, "height": 200, "commands": [ {"shape": "circle", "center": [100, 80], "radius": 50, "fill": "gold", "outline": "orange", "width": 3}, {"shape": "triangle", "points": [[50, 170], [150, 170], [100, 70]], "fill": "darkgreen"}, {"shape": "line", "start": [20, 185], "end": [180, 185], "color": "black", "width": 2} ] }

NameRequiredDescriptionDefault
widthYes
heightYes
commandsYes
output_pathYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly. It discloses that parent directories are not created, invalid commands are skipped with warnings, no-valid-command fails, later commands overpaint earlier ones, drawing outside the canvas is clipped, and colors follow specific formats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the length is justified by the tool's complexity and the absence of schema-level documentation. It is front-loaded with a one-sentence purpose, then organized into clear labeled sections with a concrete example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with four required parameters, a free-form commands array, and no annotations, the description covers nearly every decision an agent needs to make: file path rules, canvas size, command shapes, validation behavior, coordinate system, painting order, and colors. The presence of an output schema means return-value details are not required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only names and basic types, so schema coverage is effectively 0%. The description compensates completely by explaining output_path semantics, width/height meaning, command structure, all supported shape fields, defaults, and coordinate/color conventions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: it draws a picture and saves it to a file. It also distinguishes itself from the sibling draw_image by emphasizing file output, so an agent can tell the tools apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The saving-to-file behavior implies when this tool is appropriate, but the description never explicitly states when to use it versus draw_image or what conditions would favor one over the other. This is usable but implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observeddraw_image
    • First observeddraw_image_to_file
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools split cleanly by output destination: draw_image_to_file persists to disk, while draw_image returns inline PNG content. Their names and the presence of output_path only in the file variant make misselection unlikely.

Naming Consistency5/5

Both tools follow the same draw_image verb-object prefix, with the file-save variant adding the clear _to_file suffix. The naming is snake_case and consistent across the whole set.

Tool Count4/5

Two tools is slightly below the typical 3-15 range, but the count is reasonable for a narrow painter: one output mode is file saving and the other is inline PNG. It feels minimal rather than excessive.

Completeness4/5

The core draw-and-output workflow is fully covered: all five shapes, validation, coordinate handling, and both file and inline delivery are present. Minor gaps remain, such as only having a fixed white background and no text or image-import tools, though these are workaround-able or outside the narrow scope.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers