suggest MCP

Public description of the tools this server exposes. No login needed to read this page.

Version: f0ce0ea view commit
Commit date: 2026-10-03T09:02:47+02:00
Built: 2026-10-03T07:02:47Z
Started: 2026-10-07 06:59:54 UTC
Server: suggest 0.1.0
Protocol: MCP 2025-06-18, Streamable HTTP
Endpoint: https://suggest.ponelat.com/mcp
Raw JSON: schema.json

16 tools

list_directory

List the direct children (files and subdirectories) of a directory path.

Parameter	Type	Description
`path`required	string	Filesystem path, e.g. "/" or "/smokesignals/backlog"

stat

Describe a single filesystem path: whether it's a file or directory, size, mime type.

Parameter	Type	Description
`path`required	string	Filesystem path, e.g. "/" or "/smokesignals/backlog"

read_file

Read a text file's content (Markdown, YAML, JSON, plain text, ...).

Parameter	Type	Description
`path`required	string	Filesystem path, e.g. "/" or "/smokesignals/backlog"

read_binary

Read a binary file (image, etc). Returns base64-encoded content.

Parameter	Type	Description
`path`required	string	Filesystem path, e.g. "/" or "/smokesignals/backlog"

search

Search filenames and file content under a path for a text query.

Parameter	Type	Description
`query`required	string
`path`	string	Subtree to search; defaults to the whole filesystem.

write_file

Create or replace a text file. Content is the full file text. Paths the filesystem marks read-only return an error.

Parameter	Type	Description
`content`required	string	Full new text content of the file.
`path`required	string	Filesystem path of the file to write.

Start a binary upload that bypasses JSON-RPC. Returns a blob_id and a pre-signed upload_url. Upload the raw file bytes to upload_url with an HTTP PUT (no auth header needed), for example curl -sS -T ./file.png "<upload_url>", then call write_binary with the blob_id and the destination path. Use this for any file that is not tiny; it avoids putting the bytes in the conversation. The link is single-use and expires after an hour; a blob is consumed by the first successful write_binary.

No parameters.

import_url

Fetch a file from a public http(s) URL and store it as a binary file at path (same destinations as write_binary; any type, full resolution, no re-encoding). Use this when you can produce a link to the file but cannot upload bytes or run curl. The server downloads the URL itself, so it must be reachable from the public internet without login: localhost, private-network and cloud-metadata addresses are refused, redirects are followed (max 5), only http and https are accepted, and the response must be HTTP 200. Signed or expiring links are fine as long as they are still valid when the server fetches them.

Parameter	Type	Description
`path`required	string	Filesystem path to write, e.g. /myproject/design/hero.png.
`url`required	string	Public http(s) URL of the file to import.

write_binary

Create or replace a binary file at any path inside a project (project root or any subfolder; no type or size limit). Preferred: pass blob_id from create_upload after PUTting the bytes to its upload_url, so the file never passes through the conversation. For small files you may instead pass base64 (standard base64, the inverse of read_binary). Pass exactly one of blob_id or base64. If you can only provide a link, use import_url. Text files still use write_file. Paths that are generated views (PROJECT.md, backlog/*.md, milestones/*.md, sessions/...) are refused.

Parameter	Type	Description
`path`required	string	Filesystem path of the file to write.
`base64`	string	Standard base64 of the full file bytes (no data: URL prefix). Use blob_id for anything large.
`blob_id`	string	UUID from create_upload, after the bytes were uploaded to its upload_url.

make_directory

Create a directory at path. An existing directory is returned as-is. Paths the filesystem does not allow creating return an error.

Parameter	Type	Description
`path`required	string	Filesystem path, e.g. "/" or "/smokesignals/backlog"

delete_file

Delete a file at path. Directories and read-only paths return an error.

Parameter	Type	Description
`path`required	string	Filesystem path, e.g. "/" or "/smokesignals/backlog"

schedule_summary

Get the authenticated user's personal schedule for today, a week, a month, a specific date/month, or a custom date range. Returns full scheduled events, loose items needing scheduling, separately overdue unfinished loose items, counts, timezone, exclusive date bounds and generated_at. Use this for periodic AI digests; do not imply that loose items have appointments. Defaults to this week and open items. This tool does not generate prose or send messages.

Parameter	Type	Description
`from`	string	Optional custom start date YYYY-MM-DD; supply with to instead of period.
`period`	string	today, tomorrow, this week, next week, this month, next month, YYYY-MM, or YYYY-MM-DD. Weeks start Monday. Relative periods resolve using the timezone; stored loose periods never drift.
`project`	string	Optional project record ID filter; omit for the global personal schedule.
`status`	string	open (default), done, cancelled, or all.
`timezone`	string	IANA timezone; defaults to Africa/Johannesburg.
`to`	string	Exclusive custom end date YYYY-MM-DD.

schedule_get

Get one personal schedule item with all details by ID.

Parameter	Type	Description
`id`required	string	Schedule item ID.

schedule_create

Create a personal schedule item. Supply period to capture an unscheduled intention in a fixed loose window, or start/end for an actual appointment. Projects are optional tags; the schedule is global across projects.

Parameter	Type	Description
`title`required	string	Item title.
`end`	string	Timed exclusive end RFC3339 with UTC offset; must follow start.
`notes`	string	Details or notes.
`period`	string	today, tomorrow, this week, next week, this month, next month, YYYY-MM, or YYYY-MM-DD. Weeks start Monday. Relative periods resolve using the timezone; stored loose periods never drift.
`projects`	array	Optional Suggest project record IDs; empty array clears tags.
`start`	string	Timed start RFC3339 with UTC offset. Supply start/end instead of period.
`status`	string	open, done, or cancelled; defaults to open.
`timezone`	string	IANA timezone; defaults to Africa/Johannesburg.

schedule_update

Update supplied fields of a personal schedule item. Set start and end to schedule a loose item; set period to move it back to a loose window. Set status=done to finish or cancelled to cancel. Unspecified fields stay unchanged.

Parameter	Type	Description
`id`required	string	Schedule item ID.
`end`	string	Timed exclusive end RFC3339 with UTC offset; must follow start.
`notes`	string	Details or notes.
`period`	string	today, tomorrow, this week, next week, this month, next month, YYYY-MM, or YYYY-MM-DD. Weeks start Monday. Relative periods resolve using the timezone; stored loose periods never drift.
`projects`	array	Optional Suggest project record IDs; empty array clears tags.
`start`	string	Timed start RFC3339 with UTC offset. Supply start/end instead of period.
`status`	string	open, done, or cancelled; defaults to open.
`timezone`	string	IANA timezone; defaults to Africa/Johannesburg.
`title`	string	Item title.

schedule_delete

Permanently delete one personal schedule item by ID.

Parameter	Type	Description
`id`required	string	Schedule item ID.

Uploading files

Large binaries skip the conversation. Call create_upload, send the file to the returned upload_url with an HTTP PUT, then call write_binary with the blob_id and a destination path.

curl -sS -T ./file.png "<upload_url>"