KSJ MCP Server

Overview Schema Source Related Servers Discussions Admin

bulk_upload

Process all journal page photos in a folder at once: OCR each image, store captures, and file unmatched or duplicate pages as Wild Art for later review.

Instructions

Process all journal page photos in a folder at once.

Finds every image file (JPG, PNG, TIFF, BMP, WebP) in the folder and runs
the full upload pipeline on each one. Non-image files are skipped silently.
Accept-by-default: no page is skipped. Pages without a readable template
ID, or whose page ID is already taken, are stored as Wild Art (WA)
entries with the reason recorded — review them afterwards with
list_by_tag(entry_type="WA") and promote_capture(). Pass volume=N when
importing a second (or later) journal.

Note: by default this path uses local Tesseract OCR, which performs
poorly on cursive handwriting. For a handful of pages, share photos in
chat and store them via manual_capture instead. For large handwritten
imports, the user can enable cloud OCR with their own key
(KSJ_OCR_BACKEND=azure — see README); it is off by default and every
run states when it is active.

Args:
    folder_path: Absolute path to the folder containing journal photos.
    force:       Set to True to REPLACE existing captures with matching
                 template IDs (default False — the new page is filed as
                 WA with reason id_conflict; the existing one is untouched).

Returns a summary table of all processed images.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`force`	No
`volume`	No
`folder_path`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv3.9.0Oct 2, 2026
- addedInput schema / properties / volume
```
Added value: +{
+  "default": 0,
+  "title": "Volume",
+  "type": "integer"
+}
```
First observedv0.1.0Feb 20, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so: accept-by-default (no page skipped), pages with unreadable template IDs or taken IDs become Wild Art entries with a recorded reason, the default OCR backend is local Tesseract with poor cursive performance, and cloud OCR is off by default and announced per run. Mutation semantics of force (replace vs. leave existing untouched) are spelled out.

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

Conciseness4/5

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

Front-loaded with the core action, then the pipeline behavior, the OCR caveat, and an Args block — a sensible order. The only waste is the force/id_conflict behavior being stated in both the body paragraph and the Args section.

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 batch mutation tool with no annotations, the description covers side effects, fallback behavior, failure recording, OCR defaults, and follow-up remediation via list_by_tag and promote_capture. An output schema exists, so return values need no further explanation beyond the summary-table mention.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate and largely does: folder_path is documented as an absolute path, force is given detailed replace-vs-id_conflict semantics, and volume is tied to the 'second or later journal' case. Volume's default of 0 and exact effect are never explained, leaving one small gap.

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?

States a precise verb + resource + scope: it finds every image in a folder and runs the full upload pipeline on each. It is clearly distinguishable from single-page siblings like upload_capture and manual_capture, and it names the image formats it handles.

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

Usage Guidelines5/5

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

Routes the agent explicitly: for a handful of pages use manual_capture instead, and for large handwritten imports enable cloud OCR (with the env var and README pointer). It also states when volume=N should be passed. Both the alternative and the condition that selects it are given.

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