Skip to content
Back to search

director

MCP Playbooks for AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fdmtl--director/badge.svg)](/listings/fdmtl--director)

HTML

<a href="/listings/fdmtl--director"><img src="/api/listings/fdmtl--director/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

# Install Director
$ curl -LsSf https://director.run/install.sh | sh

# Start the onboarding flow
$ director quickstart

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 216 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">Director</h1>
  2. <p align="center">MCP Playbooks for AI agents</p>
  3. <p align="center"><code>curl -LsSf https://director.run/install.sh | sh</code></p>
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 4 on GitHub
  4. ---
  5. <div align="center">
  6. [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
  7. [![ci](https://github.com/director-run/director/workflows/CI/badge.svg)](https://github.com/director-run/director/actions/workflows/ci.yml)
  8. [![Release](https://github.com/director-run/director/workflows/Release/badge.svg)](https://github.com/director-run/director/actions/workflows/release.yml)
  9. [![npm](https://img.shields.io/npm/v/@director.run/cli.svg)](https://www.npmjs.com/package/@director.run/cli)
  10. </div>
  11. # Overview
  12. Director allows you to provide <ins>**playbooks**</ins> to AI Agents. A playbook is a set of <ins>**MCP tools**</ins>, <ins>**prompts**</ins> and <ins>**configuration**</ins>, that give agents new <ins>**skills**</ins>. You can connect Claude, Cursor and VSCode in 1-click, or integrate manually through a single MCP endpoint.
  13. Playbooks are portable and can easily be switched in and out of context. Director is local-first - setup and client integration takes 30 seconds. In addition, Director provides all of the MCP management functionality that you'd expect: tool filtering, logging, strong isolation, and unified OAuth.
  14. <br /><br />
  15. https://github.com/user-attachments/assets/cafc0902-a854-4ee8-ac89-b7535f10c93d
  16. ## Key Features
  17. - 📚 **Playbooks** - Maintain sets of tools, prompts and config for different tasks or environments.
  18. - 🚀 **1-Click Integration** - Switch playbooks with a single click. Currently supports Claude Code, Claude Desktop, Cursor, VSCode
  19. - 🔗 **Shareable** - Playbooks are accessible through a single MCP endpoint, making them easy to share across agents.
  20. - 🏠 **Local-First** - Director is local-first, designed to easily run on your own machine or infrastructure.
  21. - 🔑 **Unified OAuth** - Connect to OAuth MCPs centrally, and use them across all of your agents.
  22. - 🎯 **Tool Filtering** - Select only the MCP tools that are required for the specific task, preserving context.
  23. - 📊 **Observability** - Centralized JSON logging, that allows you to understand exactly what your agent is doing.
  24. - 🔌 **MCP Compliant** - Just works with any MCP server or client. Up to date with the latest MCP spec.
  25. # Quickstart
  26. ```bash
  27. # Install Director
  28. $ curl -LsSf https://director.run/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 43 on GitHub
  29. # Start the onboarding flow
  30. $ director quickstart
  31. ```
  32. # Core Concepts
  33. ## Playbooks
  34. A playbook is a set of tools, prompts and configuration, used to provide specific capabilities to your agent. Under the hood, playbooks are built on top of the MCP tools & prompts primitives.
  35. The easiest way to author a playbook is via the UI (`director studio`). But you can also use the CLI. You can have many playbooks, typically one per task or per environment. You can connect to them via a single CLI command or directly over a URL.
  36. ## Architecture
  37. At a high level, Director is a service that sits between your agents and MCP servers. It's transparent to clients, requiring no additional tokens. It models playbooks, which can be thought of as standalone, portable skills that enhance your AI agent with new capabilities.
  38. <img src="https://github.com/director-run/director/blob/main/apps/docs/images/director-highlevel-overview.png" width="100%" alt="director demo">
  39. # Usage
  40. ## Installation
  41. ```bash
  42. # Install the director CLI + dependencies (node, npm & uvx) via the 1-liner:
  43. $ curl -LsSf https://director.run/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 68 on GitHub
  44. # Alternatively, install through npm:
  45. $ npm install -g @director.run/cli
  46. # Start director & open the UI
  47. $ director quickstart
  48. ```
  49. ## The Studio (Web UI)
  50. The simplest way to interact with director is via the admin interface:
  51. ```bash
  52. # Open studio in your browser
  53. $ director studio
  54. ```
  55. ## CLI Reference
  56. ```bash
  57. Playbooks for your AI agent
  58. USAGE
  59. director <command> [subcommand] [flags]
  60. CORE COMMANDS
  61. quickstart Start the gateway and open the studio in your browser
  62. serve Start the web service
  63. studio Open the UI in your browser
  64. ls List playbooks
  65. get <playbookId> [serverName] Show playbook details
  66. auth <playbookId> <server> Authenticate a server
  67. create <name> Create a new playbook
  68. destroy <playbookId> Delete a playbook
  69. connect <playbookId> [options] Connect a playbook to a MCP client
  70. disconnect <playbookId> [options] Disconnect a playbook from an MCP client
  71. add <playbookId> [options] Add a server to a playbook.
  72. remove <playbookId> <serverName> Remove a server from a playbook
  73. update <playbookId> [serverName] [options] Update playbook attributes
  74. http2stdio <url> Proxy an HTTP connection (sse or streamable) to a stdio stream
  75. env [options] Print environment variables
  76. status Get the status of the director
  77. REGISTRY
  78. registry ls List all available servers in the registry
  79. registry get <entryName> Get detailed information about a registry item
  80. registry readme <entryName> Print the readme for a registry item
  81. MCP
  82. mcp list-tools <playbookId> List tools on a playbook
  83. mcp get-tool <playbookId> <toolName> Get the details of a tool
  84. mcp call-tool <playbookId> <toolName> [options] Call a tool on a playbook
  85. PROMPTS
  86. prompts ls <playbookId> List all prompts for a playbook
  87. prompts add <playbookId> Add a new prompt to a playbook
  88. prompts edit <playbookId> <promptName> Edit an existing prompt
  89. prompts remove <playbookId> <promptName> Remove a prompt from a playbook
  90. prompts get <playbookId> <promptName> Show the details of a specific prompt
  91. FLAGS
  92. -V, --version output the version number
  93. EXAMPLES
  94. $ director create my-playbook # Create a new playbook
  95. $ director add my-playbook --entry fetch # Add a server to a playbook
  96. $ director connect my-playbook --target claude # Connect my-playbook to claude
  97. ```
  98. ### TypeScript SDK
  99. Programmatic control for advanced use cases:
  100. ```typescript
  101. import { Gateway, GatewayConfig } from "@director.run/sdk";
  102. // Start the gateway
  103. const gateway = await Gateway.start({
  104. config: await GatewayConfig.createMemoryBasedConfig({
  105. defaults: {
  106. server: {
  107. port: 3673,
  108. },
  109. },
  110. }),
  111. baseUrl: "http://localhost:3673",
  112. });
  113. // Add a new playbook
  114. await gateway.playbookStore.create({
  115. name: "test",
  116. servers: [
  117. {
  118. name: "notion",
  119. type: "http",
  120. url: "https://mcp.notion.com/mcp",
  121. },
  122. ],
  123. });
  124. ```
  125. # Repository Structure
  126. ### External Apps
  127. - [`apps/gateway`](./apps/gateway/README.md) - Core gateway and playbook logic
  128. - [`apps/cli`](./apps/cli/README.md) - The command-line interface, the primary way to interact with Director. Available on [npm](https://www.npmjs.com/package/@director.run/cli).
  129. - [`apps/sdk`](./apps/sdk/README.md) - The Typescript SDK, available on [npm](https://www.npmjs.com/package/@director.run/sdk).
  130. - [`apps/docker`](./apps/docker/README.md) - The Director docker image, which allows you to run Director (and all MCP servers) securely inside a container. Available on [Docker Hub](https://hub.docker.com/r/barnaby/director).
  131. - [`apps/docs`](./apps/docs/README.md) - Project documentation hosted at [https://docs.director.run](https://docs.director.run)
  132. - [`apps/registry`](./apps/registry/README.md) - Backend for the registry hosted at [https://registry.director.run](https://registry.director.run)
  133. - [`apps/studio`](./apps/studio/README.md) - Director frontend application
  134. ### Internal Packages
  135. - [`packages/client-configurator`](./packages/client-configurator/README.md) - Library for managing MCP client configuration files
  136. - [`packages/mcp`](./packages/mcp/README.md) - Extensions to MCP SDK that add middleware functionality
  137. - [`packages/utilities`](./packages/utilities/README.md) - Shared utilities used across all packages and apps
  138. - [`packages/design`](./packages/design/README.md) - Design system: reusable UI components, hooks, and styles for all Director apps
  139. *This is a monorepo managed by [Turborepo](https://turbo.build/).*
  140. # Community
  141. If you're using director, have any ideas, or just want to chat about MCP, we'd love to chat:
  142. - 💬 Join our [Discord](https://discord.gg/kWZGvWks)
  143. - 📧 Send us an [Email](mailto:hello@director.run)
  144. - 🐛 Report a [Bug](https://github.com/director-run/director/issues)
  145. - 🐦 Follow us on [X / Twitter](https://x.com/barnabymalet)
  146. # Contributing
  147. We welcome contributions! See [CONTRIBUTING.mdx](./apps/docs/project/contributing.mdx) for guidelines.
  148. ## Setting up Development Environment
  149. ```bash
  150. # Fork and clone
  151. git clone https://github.com/director_run/director
  152. cd director
  153. ./scripts/setup-development.sh
  154. bun run test
  155. ```
  156. # License
  157. AGPL v3 - See [LICENSE](./LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.