Prompt Commands

The guide prompt provides a comprehensive command system for direct access to MCP documents and functionality. Commands let you view project information, manage content, control workflows, and configure permissions. All commands follow a consistent structure with built-in help.

Not all agents support MCP prompts. All prompt commands are also available as guide:// URI resources — for example, @guide :status is equivalent to guide://_status. See Guide URIs for details.

A note on prompt prefixes: The examples in this document use @guide as the prompt prefix, but your agent may use a different prefix such as /guide. Treat @ as a placeholder — use whatever prefix your agent provides.

Command Structure

Commands are invoked through the guide prompt with this syntax:

@guide :command [args] [--flags]

Flag Syntax: Commands support two syntaxes for flags with values: - --flag=value (always supported) - --flag value (supported when flag is declared with argrequired)

Examples:

@guide :help
@guide :status
@guide :project
@guide :flags
@guide :create/category docs
@guide :workflow/issue --tracking MRP-177
@guide :flags/project/set workflow --value=true

Discovery with @guide :help

The @guide :help prompt command is your primary discovery mechanism. Use it to explore available commands and their usage:

@guide :help              # Show all available commands grouped by category
@guide :help <command>    # Show detailed help for a specific command

Recommended pattern: 1. Start with @guide :help to see available commands 2. Use @guide :help <command> for specific command usage 3. Execute the command 4. Use @guide :help again to discover related commands

Core Information Commands

@guide :status Shows system status and current project information including active project, workflow phase (if enabled), and OpenSpec integration status.

@guide :project (:info/project, :project/info) Displays comprehensive project information including project name, categories, collections, feature flags, and filesystem permissions. Use --verbose or -v for detailed output including all category patterns.

@guide :flags Shows all feature flags affecting the current project - feature flags (apply to all projects by default), project-specific flags (override feature flags), and resolved values (what the agent actually sees). Lists available flags with their scope restrictions (Project only, Feature only, or both).

@guide :system (:info/system) Displays system information for both the MCP server and the agent's client environment. Server information (OS, platform, hostname, Python version, working directory) is always shown. Client information (agent's OS, hostname, user, git remotes) requires the allow-client-info feature flag to be enabled.

The allow-client-info Feature Flag

Client information collection is gated behind the allow-client-info feature flag due to privacy concerns. This flag is normally set globally (affects all projects) and defaults to false. It collects information about the agent's environment (OS, hostname, user) and requires explicit opt-in to respect user privacy. Ask the agent to set the allow-client-info feature flag to true to enable it.

Project Management Commands

Category Management

@guide :project/category (:category) Shows category overview with list of current categories and available commands.

@guide :project/category/list (:category/list) Lists all categories in the current project. Use --verbose for detailed information including directories and patterns.

@guide :project/category/add (:category/add) Creates a new category for organising project content. Categories define directories and file patterns for content discovery.

Examples:

@guide :category/add docs
@guide :category/add docs --dir=documentation --patterns=README,CONTRIBUTING
@guide :category/add testing --description="Testing Guidelines"

Parameters: - name (required) - Category name - --dir=<path> - Directory path (defaults to category name) - --patterns=<patterns> - Comma-separated file patterns (e.g., README,CONTRIBUTING,test_) - --description=<text> - Human-readable description

@guide :project/category/remove (:category/remove) Removes a category from the project.

@guide :project/category/change (:category/change) Changes category properties.

Examples:

@guide :category/change docs --new-name=documentation
@guide :category/change docs --new-dir=doc --new-patterns=README,INSTALL

@guide :project/category/update (:category/update) Updates category patterns incrementally without replacing all properties.

Examples:

@guide :category/update docs --add-patterns=CHANGELOG,AUTHORS
@guide :category/update docs --remove-patterns=old-file

@guide :project/category/files (:category/files) Lists all files in a category directory.

Collection Management

@guide :project/collection (:collection) Shows collection overview with list of current collections and available commands.

@guide :project/collection/list (:collection/list) Lists all collections in the current project. Use --verbose for detailed information including categories and descriptions.

@guide :project/collection/add (:collection/add) Creates a new collection that groups multiple categories or other collections together.

Examples:

@guide :collection/add docs
@guide :collection/add api-docs --categories=code,examples
@guide :collection/add beginner --categories=docs,examples --description="Getting started content"

Parameters: - name (required) - Collection name - --categories=<categories> - Comma-separated category or collection names - --description=<text> - Human-readable description

@guide :project/collection/remove (:collection/remove) Removes a collection from the project.

@guide :project/collection/change (:collection/change) Changes collection properties.

Examples:

@guide :collection/change docs --new-name=documentation
@guide :collection/change docs --new-categories=guide,lang,context

@guide :project/collection/update (:collection/update) Updates collection categories incrementally.

Examples:

@guide :collection/update docs --add-categories=context
@guide :collection/update docs --remove-categories=old-category

Collections enable logical grouping of related content for easier access through the @guide prompt.

Feature Flag Commands

Project Flags

@guide :flags/project Shows project flag overview and available commands.

@guide :flags/project/list (:flags/project/list) Lists all project-specific feature flags. Use --active to show only active flags.

@guide :flags/project/get (:flags/project/get) Gets the value of a specific project flag.

Example:

@guide :flags/project/get workflow

@guide :flags/project/set (:flags/project/set) Sets a project-specific feature flag value.

Examples:

@guide :flags/project/set workflow
@guide :flags/project/set workflow false
@guide :flags/project/set content-format --value=mime

@guide :flags/project/remove (:flags/project/remove) Removes a project-specific flag override, reverting to the feature flag value.

Example:

@guide :flags/project/remove workflow

Feature Flags

@guide :flags/feature Shows feature flag overview and available commands.

@guide :flags/feature/list (:flags/feature/list) Lists all feature flags (apply across all projects). Use --active to show only active flags.

@guide :flags/feature/get (:flags/feature/get) Gets the value of a specific feature flag.

Example:

@guide :flags/feature/get autoupdate

@guide :flags/feature/set (:flags/feature/set) Sets a feature flag value.

Examples:

@guide :flags/feature/set workflow
@guide :flags/feature/set workflow false
@guide :flags/feature/set content-format --value=mime

@guide :flags/feature/remove (:flags/feature/remove) Removes a feature flag.

Example:

@guide :flags/feature/remove autoupdate

Available Flags

• workflow - Enable workflow phase tracking (Project and Feature)
• openspec - Enable OpenSpec integration (Project and Feature)
• content-style - Markdown formatting: plain, headings, or full (Project and Feature)
• content-format - Content MIME type: text or mime (Project and Feature)
• autoupdate - Automatic content updates (Feature only)

Document Commands

Document commands let you manage stored documents — content that lives in the document store rather than as files on disk. See Stored Documents for the full picture.

@guide :document Shows available document commands.

@guide :document/add <category> <path> Adds a local file to the document store in the specified category.

Examples:

@guide :document/add docs /path/to/file.md
@guide :document/add docs /path/to/file.md --as custom-name
@guide :document/add docs /path/to/file.md --force
@guide :document/add docs /path/to/file.md --agent-instruction

@guide :document/add-url <category> <url> Fetches content from a URL and stores it in the specified category.

Examples:

@guide :document/add-url docs https://example.com/api-reference
@guide :document/add-url docs https://example.com/guide --as api-guide

@guide :document/list <category> Lists stored documents in a category.

@guide :document/show <category> <name> Displays the content of a stored document.

@guide :document/update <category> <name> Updates a stored document's name, category, or metadata.

@guide :document/remove <category> <name> Removes a stored document from a category.

Export Commands

Export commands manage tracked content exports — rendered content saved to files for knowledge persistence. See Content Management for how exports work.

@guide :export/add <expression> <path> Exports rendered content to a file and tracks it.

Examples:

@guide :export/add docs documentation.md
@guide :export/add architecture arch.md --force

@guide :export/list Lists all tracked exports with their expression, path, and staleness status.

@guide :export/remove <expression> Removes an export tracking entry (does not delete the exported file).

Filesystem Permissions

mcp-guide implements built-in security controls to ensure agent instructions don't transgress security boundaries outside the project.

Security Model

Read permissions: - Project directory: Always readable (default) - Additional paths: Must be explicitly allowed via additional_read_paths in .guide.yaml - System directories: Always blocked (e.g., /etc, /System, C:\Windows)

Write permissions: - Controlled by allowed_write_paths in .guide.yaml - Paths must be relative to project root - Must end with trailing slash for directories (e.g., src/, docs/) - Default: Empty list (no writes allowed outside explicit configuration)

Temporary files: - Safe temp paths are allowed for read/write - System validates temp directory safety

Viewing Permissions

@guide :project/perm (:perm) Shows current filesystem permissions configuration for the project - read permissions (project directory + additional paths) and write permissions (allowed write paths).

Managing Permissions

Permissions are configured in .guide.yaml:

allowed_write_paths:
  - src/
  - docs/

additional_read_paths:
  - /absolute/path/to/external/docs

Write paths: - Must be relative to project root - Can be specific files or directories (end with / for directories) - Examples: src/, docs/, config.json, .guide.yaml

Read paths: - Must be absolute paths - Cannot be system directories - Examples: /Users/name/external, /home/user/docs

Security Violations

When an agent attempts to read or write outside permitted paths, the operation is blocked, a SecurityError is raised, the violation is logged, and the agent receives an error message. This ensures that even if an agent is instructed to access restricted paths, the MCP server enforces security boundaries.

Workflow Commands

When the workflow feature flag is enabled, additional workflow commands become available. See Workflows for complete documentation.

OpenSpec Commands

When OpenSpec integration is enabled, OpenSpec commands provide access to spec-driven development features. See OpenSpec Integration for complete documentation.