4.8 KiB

Raw Permalink Blame History

Configuration Files

This directory contains example configuration files for the Claude Code SDK in both JSON and YAML formats.

Directory Structure

config/
├── json/           # JSON format configurations
│   ├── config.json
│   ├── mcpconfig.json
│   └── roles.json
└── yaml/           # YAML format configurations
    ├── config.yaml
    ├── mcpconfig.yaml
    └── roles.yaml

File Descriptions

1. General Configuration (`config.json/yaml`)

General project and SDK settings including:

Project metadata
SDK timeout and retry settings
Claude model configuration
Logging preferences
Development settings

2. MCP Server Permissions (`mcpconfig.json/yaml`)

Model Context Protocol server-level permissions:

Global settings (model, timeout, permission mode)
Server-specific permissions (file-system, database, git, etc.)
Tool-level allow/deny lists
Environment variables

3. Role-Based Access Control (`roles.json/yaml`)

Role definitions with specific permissions and contexts:

Pre-defined roles (developer, dataAnalyst, securityAuditor, etc.)
Permission modes and tool access
Prompting templates with variable substitution
Role inheritance (e.g., seniorDeveloper extends developer)

YAML vs JSON

Why Use YAML?

Better Readability

# Clear structure without quotes and commas
model: opus
timeout: 30000

Comments Support

# This server handles all file operations
file-system-mcp:
  defaultPermission: allow  # Be careful with this!

Multi-line Strings

promptingTemplate: |
  You are a ${language} developer.
  Focus on clean, maintainable code.
  Follow best practices.

Anchors & References

defaults: &defaults
  model: sonnet
  timeout: 30000

globalSettings:
  <<: *defaults
  permissionMode: ask

Environment Variables

cwd: ${HOME}/projects
authToken: ${CLAUDE_AUTH_TOKEN}

When to Use JSON?

When integrating with systems that only support JSON
When you need strict schema validation
For programmatic generation/manipulation
When file size is critical (JSON is slightly smaller)

Usage Examples

Loading Configuration Files

import { claude } from '@instantlyeasy/claude-code-sdk-ts';

// Auto-detects format based on file extension
const builder = await claude()
  .withConfigFile('./config/yaml/mcpconfig.yaml');

// Or use JSON
const builder = await claude()
  .withConfigFile('./config/json/mcpconfig.json');

// Load multiple configurations
const builder = claude();
await builder.withConfigFile('./config/yaml/mcpconfig.yaml');
await builder.withRolesFile('./config/yaml/roles.yaml');

Applying Roles

// Apply a role with template variables
builder.withRole('developer', {
  language: 'TypeScript',
  framework: 'React'
});

// The role's prompting template will be interpolated:
// "You are a TypeScript developer with expertise in React."

Environment Variable Expansion

Environment variables in configurations are automatically expanded:

globalSettings:
  cwd: ${HOME}/projects      # Expands to /Users/username/projects
  env:
    AUTH_TOKEN: ${AUTH_TOKEN} # Expands from process.env.AUTH_TOKEN

Best Practices

Use YAML for Human-Edited Configs
- Better readability
- Inline documentation with comments
- Easier to maintain
Use JSON for Machine-Generated Configs
- Programmatic generation
- Strict parsing
- Universal support

Organize by Environment

config/
├── development/
├── staging/
└── production/

Version Control Considerations
- Commit example configs
- Use .gitignore for environment-specific configs
- Document required environment variables
Security
- Never commit sensitive data (auth tokens, passwords)
- Use environment variables for secrets
- Review permission settings carefully

Converting Between Formats

JSON to YAML

# Using Python (if available)
python -c "import json, yaml; print(yaml.dump(json.load(open('config.json'))))" > config.yaml

# Using Node.js
node -e "console.log(require('js-yaml').dump(require('./config.json')))" > config.yaml

YAML to JSON

# Using Python (if available)
python -c "import json, yaml; print(json.dumps(yaml.safe_load(open('config.yaml')), indent=2))" > config.json

# Using Node.js
node -e "console.log(JSON.stringify(require('js-yaml').load(require('fs').readFileSync('./config.yaml', 'utf8')), null, 2))" > config.json

Schema Reference

For detailed schema documentation, see:

4.8 KiB Raw Permalink Blame History