project_query
read
beta
auth: project:read
approval: never
status: v1
List accessible projects, read one project by stable id, or re-find a project by exact name.
When to use
Use when the caller wants lightweight project discovery, one project summary, or to recover a project id by exact name before follow-up mutations.
When not to use
Do not use for screenplay content or story-graph mutations.
Examples
“List my projects.”
“Read the project with id 123.”
“Find the project named Scenario MCP Test.”
Anti-examples
- Rewrite scene 5 in my screenplay.
Backend capabilities
project.list
project.get
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
project_query input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"list",
"get",
"name_exact",
"search"
]
},
"project_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"query": {
"type": "string"
},
"cursor": {
"type": [
"string",
"null"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200
}
},
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "get"
}
}
},
"then": {
"required": [
"project_id"
]
}
},
{
"if": {
"properties": {
"mode": {
"const": "name_exact"
}
}
},
"then": {
"required": [
"name"
]
}
},
{
"if": {
"properties": {
"mode": {
"const": "search"
}
}
},
"then": {
"required": [
"query"
]
}
}
],
"additionalProperties": false
}Output schema
project_query output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string"
},
"projects": {
"type": "array",
"items": {
"type": "object"
}
},
"project": {
"type": "object"
},
"project_id": {
"type": [
"integer",
"null"
]
},
"project_name": {
"type": [
"string",
"null"
]
},
"project_mode": {
"type": [
"string",
"null"
]
},
"project_updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recommended_screenplay_workflow": {
"type": [
"string",
"null"
],
"description": "Recommended screenplay_generation_run workflow for this project's template mode."
},
"template_pipeline": {
"type": "object",
"description": "Compact MCP routing hints derived from the project's template pipeline."
},
"project_summary": {
"type": [
"object",
"null"
],
"description": "Compact 'what already exists' signal for a single-project get: derived `state` (empty_project | story_outline_ready | screenplay_ready | media_ready | active_job) and `card_counts` (story_cards, scenes, episodes, screenplay, shots, media). Use it to avoid re-running a stage whose output already exists.",
"properties": {
"state": {
"type": [
"string",
"null"
]
},
"card_counts": {
"type": "object"
}
}
},
"match_count": {
"type": "integer"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
}
},
"additionalProperties": true
}← All toolsv1 · query_tool