Commands

The guide:// URI scheme provides the canonical command interface 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.

Prompt-style invocation may also be available in some clients, but this document uses guide:// as the primary form. See Guide URIs for details.

Note: If your client supports prompts, equivalent forms like @<prompt> :status or /<prompt> :status may also work. The exact prompt name can vary.

Command Structure

Commands are invoked 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 command resource 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/flags        # 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%20Guidelines

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%20started%20content

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 guide:// expressions.

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/%2Fpath%2Fto%2Ffile.md
guide://_document/add/docs/%2Fpath%2Fto%2Ffile.md?as=custom-name
guide://_document/add/docs/%2Fpath%2Fto%2Ffile.md?force
guide://_document/add/docs/%2Fpath%2Fto%2Ffile.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%3A%2F%2Fexample.com%2Fapi-reference
guide://_document/add-url/docs/https%3A%2F%2Fexample.com%2Fguide?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.