How to Use Local File Paths and Git Repositories as Sources in Craft Agents

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/<workspace-id>/sources/<slug>/.

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:

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/<ws>/sources/my-docs/ and populates it with config.json and guide.md.

Configuration Schema

The auto-generated config.json in ~/.craft-agent/workspaces/<ws>/sources/<slug>/ follows this structure:

{
  "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:

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 file in the source directory:

{
  "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:

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/<ws>/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:

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:

{
  "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/<workspace-id>/sources/<slug>/ and are validated against TypeScript definitions in packages/shared/src/resources/. The authoritative documentation in 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: Contains the source definition and connection parameters.
• guide.md: Auto-generated human-readable documentation for the agent.
• 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/<ws>/sources/<slug>/.
• Validate all sources with craft-agent source test <slug> before use.
• Restrict agent capabilities using allowedBashPatterns for local sources or allowedMcpPatterns for Git repositories in 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/<ws>/sources/<slug>/config.json and run craft-agent source test <slug> 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 <slug> --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/<workspace-id>/sources/<slug>/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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}