claude-web/node_modules/@instantlyeasy/claude-code-sdk-ts/examples/config

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?

1. Better Readability

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

2. Comments Support

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

3. Multi-line Strings

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

4. Anchors & References

   defaults: &defaults
     model: sonnet
     timeout: 30000
   
   globalSettings:
     <<: *defaults
     permissionMode: ask
   

5. 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

1. Use YAML for Human-Edited Configs

   • Better readability
   • Inline documentation with comments
   • Easier to maintain

2. Use JSON for Machine-Generated Configs

   • Programmatic generation
   • Strict parsing
   • Universal support

3. Organize by Environment

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

4. Version Control Considerations

   • Commit example configs
   • Use .gitignore for environment-specific configs
   • Document required environment variables

5. 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:

• Configuration Types
• Role Types
• Permission Types