# How to Use Local File Paths and Git Repositories as Sources in Craft Agents > Learn to use local file paths and Git repositories as sources in Craft Agents. Configure directories as local sources and Git repos as mcp sources with the craft-agent CLI. - Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss) - Tags: how-to-guide - Published: 2026-07-04 --- **You can configure local directories as `type: "local"` sources and Git repositories as `type: "mcp"` sources using the `craft-agent source create` CLI command, which writes validated configuration files to `~/.craft-agent/workspaces//sources//`.** Craft Agents in the `craft-ai-agents/craft-agents-oss` repository access data through **sources**—structured JSON configurations that define where information originates. Whether you need to query files on your local machine or interact with GitHub via the Model Context Protocol (MCP), the CLI-first workflow generates the necessary schema and validates it with `source_test`. ## Creating Local File System Sources Local sources enable agents to execute bash-style commands like `ls`, `cat`, and `grep` against directories on your machine. ### CLI Command Structure Run the `craft-agent source create` command with `--type local` and `--provider filesystem`: ```bash craft-agent source create \ --name "My Docs" \ --slug my-docs \ --provider filesystem \ --type local \ --path "$HOME/Documents/ProjectNotes" ``` This creates the directory `~/.craft-agent/workspaces//sources/my-docs/` and populates it with [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) and [`guide.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/guide.md). ### Configuration Schema The auto-generated [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) in `~/.craft-agent/workspaces//sources//` follows this structure: ```json { "id": "my-docs_a1b2c3d4", "name": "My Docs", "slug": "my-docs", "enabled": true, "provider": "filesystem", "type": "local", "local": { "path": "/home/you/Documents/ProjectNotes" } } ``` Required fields include `id`, `name`, `slug`, `provider`, and `type`, with the filesystem path specified under the `local.path` key. ### Validation and Permissions Validate the source configuration using: ```bash craft-agent source test my-docs ``` The `source_test` command verifies that `local.path` exists and is readable. To restrict agents to read-only operations, create a [`permissions.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/permissions.json) file in the source directory: ```json { "allowedBashPatterns": [ { "pattern": "^(ls|cat|head|tail|grep|find|tree)\\s", "comment": "Read-only file ops" } ] } ``` ## Connecting Git Repositories as MCP Sources Git repositories from GitHub, GitLab, and other VCS providers integrate as **MCP sources** (`type: "mcp"`), exposing repository tools through the Model Context Protocol. ### GitHub and GitLab Setup Create an MCP source by specifying the provider and endpoint URL: ```bash craft-agent source create \ --name "Craft GitHub" \ --slug github-craft \ --provider github \ --type mcp \ --url "https://api.github.com/mcp/" \ --auth-type bearer ``` This writes the configuration to `~/.craft-agent/workspaces//sources/github-craft/config.json` with `provider` set to the VCS service and `type` set to `"mcp"`. ### Authentication Configuration For private repositories, use `authType: "bearer"` and provide a Personal Access Token (PAT). Public repositories can use `authType: "none"`. After creating the source, validate connectivity and store credentials: ```bash craft-agent source test github-craft craft-agent source credential-prompt github-craft --mode bearer ``` The credential prompt securely stores the PAT for reuse in future sessions. ### MCP Tool Permissions Control which MCP tools are available by editing [`permissions.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/permissions.json): ```json { "allowedMcpPatterns": [ { "pattern": "^list$", "comment": "List repos, branches, files" }, { "pattern": "^get$", "comment": "Read file contents" }, { "pattern": "^search$", "comment": "Search code" } ] } ``` These patterns determine whether Claude can invoke tools like `github__listRepos`, `github__getFile`, or `github__searchCode`. ## Source Architecture and Validation All source configurations reside in `~/.craft-agent/workspaces//sources//` and are validated against TypeScript definitions in `packages/shared/src/resources/`. The authoritative documentation in [`apps/electron/resources/docs/sources.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/sources.md) defines the complete schema for both local and MCP source types. The CLI generates three core files for every source: - [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json): Contains the source definition and connection parameters. - [`guide.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/guide.md): Auto-generated human-readable documentation for the agent. - [`permissions.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/permissions.json): Optional fine-grained access controls for bash or MCP patterns. ## Summary - **Local sources** use `type: "local"` and `provider: "filesystem"` to expose directories for bash command execution. - **Git sources** use `type: "mcp"` with providers like `github` or `gitlab` to expose repository tools via the Model Context Protocol. - The `craft-agent source create` CLI validates inputs and writes configurations to `~/.craft-agent/workspaces//sources//`. - Validate all sources with `craft-agent source test ` before use. - Restrict agent capabilities using `allowedBashPatterns` for local sources or `allowedMcpPatterns` for Git repositories in [`permissions.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/permissions.json). ## Frequently Asked Questions ### How do I update an existing source configuration? Run the `craft-agent source create` command with the same `--slug` to overwrite the existing configuration, or manually edit `~/.craft-agent/workspaces//sources//config.json` and run `craft-agent source test ` to validate the changes according to the schemas in `packages/shared/src/resources/`. ### Can I use local file paths and Git repositories simultaneously in the same workspace? Yes. Craft Agents supports multiple concurrent sources. Create separate slugs for each source—one with `--type local` for filesystem access and another with `--type mcp` for Git repository access. Both configurations coexist in the `sources/` directory under their respective slugs. ### What authentication methods are supported for private Git repositories? For private repositories, use `--auth-type bearer` when creating the source, then execute `craft-agent source credential-prompt --mode bearer` to securely store a Personal Access Token. Public repositories can use `--auth-type none` for unauthenticated access. ### Where are source configurations stored and how are they validated? Source configurations are stored in `~/.craft-agent/workspaces//sources//config.json`. The `craft-agent source test` command validates these files against TypeScript schemas defined in `packages/shared/src/resources/` and checks connectivity for MCP sources or filesystem accessibility for local sources.