From 050a7865004c2c5aed8cfc2035af16e287cd185d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Nov 2025 15:26:18 +0000 Subject: [PATCH] Add comprehensive VitePress documentation site Created a complete VitePress documentation site for Studio MCP with: - Home page with feature highlights and quick start - Guide section: - What is Studio MCP - Getting started guide - Installation instructions - Configuration guides for Claude Desktop, Cursor, and VSCode - Debugging guide - Development guide - Reference section: - Template syntax reference - CLI options reference - Architecture documentation - Examples section: - Basic examples - Common tools (git, npm, docker, curl, etc.) - Advanced use cases - VitePress configuration with navigation and search - Package.json with dev/build/preview scripts - Documentation README for contributors --- docs/.gitignore | 4 + docs/.vitepress/config.ts | 78 +++ docs/README.md | 117 ++++ docs/examples/advanced.md | 963 ++++++++++++++++++++++++++++++ docs/examples/basic.md | 615 +++++++++++++++++++ docs/examples/common-tools.md | 798 +++++++++++++++++++++++++ docs/guide/config-claude.md | 344 +++++++++++ docs/guide/config-cursor.md | 371 ++++++++++++ docs/guide/config-vscode.md | 466 +++++++++++++++ docs/guide/debugging.md | 425 +++++++++++++ docs/guide/development.md | 447 ++++++++++++++ docs/guide/getting-started.md | 215 +++++++ docs/guide/installation.md | 299 ++++++++++ docs/guide/what-is-studio.md | 95 +++ docs/index.md | 86 +++ docs/package.json | 14 + docs/reference/architecture.md | 680 +++++++++++++++++++++ docs/reference/cli-options.md | 471 +++++++++++++++ docs/reference/template-syntax.md | 498 +++++++++++++++ 19 files changed, 6986 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/.vitepress/config.ts create mode 100644 docs/README.md create mode 100644 docs/examples/advanced.md create mode 100644 docs/examples/basic.md create mode 100644 docs/examples/common-tools.md create mode 100644 docs/guide/config-claude.md create mode 100644 docs/guide/config-cursor.md create mode 100644 docs/guide/config-vscode.md create mode 100644 docs/guide/debugging.md create mode 100644 docs/guide/development.md create mode 100644 docs/guide/getting-started.md create mode 100644 docs/guide/installation.md create mode 100644 docs/guide/what-is-studio.md create mode 100644 docs/index.md create mode 100644 docs/package.json create mode 100644 docs/reference/architecture.md create mode 100644 docs/reference/cli-options.md create mode 100644 docs/reference/template-syntax.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..3945675 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,4 @@ +node_modules +.vitepress/dist +.vitepress/cache +.DS_Store diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts new file mode 100644 index 0000000..b7492fe --- /dev/null +++ b/docs/.vitepress/config.ts @@ -0,0 +1,78 @@ +import { defineConfig } from 'vitepress' + +export default defineConfig({ + title: 'Studio MCP', + description: 'Turn any CLI command into an MCP tool', + + themeConfig: { + logo: '/logo.svg', + + nav: [ + { text: 'Guide', link: '/guide/getting-started' }, + { text: 'Reference', link: '/reference/template-syntax' }, + { text: 'Examples', link: '/examples/basic' }, + { text: 'GitHub', link: 'https://github.com/studio-mcp/studio' } + ], + + sidebar: { + '/guide/': [ + { + text: 'Introduction', + items: [ + { text: 'What is Studio MCP?', link: '/guide/what-is-studio' }, + { text: 'Getting Started', link: '/guide/getting-started' }, + { text: 'Installation', link: '/guide/installation' } + ] + }, + { + text: 'Configuration', + items: [ + { text: 'Claude Desktop', link: '/guide/config-claude' }, + { text: 'Cursor', link: '/guide/config-cursor' }, + { text: 'VSCode', link: '/guide/config-vscode' } + ] + }, + { + text: 'Advanced', + items: [ + { text: 'Debugging', link: '/guide/debugging' }, + { text: 'Development', link: '/guide/development' } + ] + } + ], + '/reference/': [ + { + text: 'Reference', + items: [ + { text: 'Template Syntax', link: '/reference/template-syntax' }, + { text: 'Command Line Options', link: '/reference/cli-options' }, + { text: 'Architecture', link: '/reference/architecture' } + ] + } + ], + '/examples/': [ + { + text: 'Examples', + items: [ + { text: 'Basic Examples', link: '/examples/basic' }, + { text: 'Common Tools', link: '/examples/common-tools' }, + { text: 'Advanced Use Cases', link: '/examples/advanced' } + ] + } + ] + }, + + socialLinks: [ + { icon: 'github', link: 'https://github.com/studio-mcp/studio' } + ], + + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2025 Martin Emde' + }, + + search: { + provider: 'local' + } + } +}) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7efd3de --- /dev/null +++ b/docs/README.md @@ -0,0 +1,117 @@ +# Studio MCP Documentation + +This directory contains the VitePress documentation site for Studio MCP. + +## Getting Started + +### Install Dependencies + +```bash +cd docs +npm install +``` + +### Development Server + +Run the local development server: + +```bash +npm run dev +``` + +The site will be available at `http://localhost:5173` + +### Build for Production + +Build the static site: + +```bash +npm run build +``` + +Output will be in `.vitepress/dist/` + +### Preview Production Build + +Preview the production build locally: + +```bash +npm run preview +``` + +## Documentation Structure + +``` +docs/ +├── .vitepress/ +│ └── config.ts # VitePress configuration +├── guide/ # User guides +│ ├── what-is-studio.md +│ ├── getting-started.md +│ ├── installation.md +│ ├── config-claude.md +│ ├── config-cursor.md +│ ├── config-vscode.md +│ ├── debugging.md +│ └── development.md +├── reference/ # API and technical reference +│ ├── template-syntax.md +│ ├── cli-options.md +│ └── architecture.md +├── examples/ # Examples and tutorials +│ ├── basic.md +│ ├── common-tools.md +│ └── advanced.md +└── index.md # Home page +``` + +## Adding Content + +### New Guide Page + +1. Create a new `.md` file in the appropriate directory +2. Add frontmatter if needed +3. Update `.vitepress/config.ts` sidebar configuration + +### New Example + +1. Add example to `examples/` directory +2. Update sidebar in `.vitepress/config.ts` +3. Link from related pages + +## Writing Tips + +- Use clear, concise language +- Include code examples for every feature +- Add links to related sections +- Test all code examples +- Use proper markdown formatting + +## VitePress Features + +- **Markdown Extensions**: Enhanced markdown with custom containers +- **Code Blocks**: Syntax highlighting and line numbers +- **Search**: Built-in search functionality +- **Mobile Responsive**: Works on all devices +- **Fast**: Static site generation for performance + +## Deployment + +The documentation can be deployed to: + +- GitHub Pages +- Netlify +- Vercel +- Any static hosting service + +Just build the site and deploy the `.vitepress/dist` directory. + +## Contributing + +When contributing to the documentation: + +1. Follow the existing structure +2. Maintain consistent tone and style +3. Test all code examples +4. Check for broken links +5. Preview changes locally before committing diff --git a/docs/examples/advanced.md b/docs/examples/advanced.md new file mode 100644 index 0000000..9c87a59 --- /dev/null +++ b/docs/examples/advanced.md @@ -0,0 +1,963 @@ +# Advanced Examples + +This guide covers advanced use cases and complex tool configurations. + +## Multiple Templates in URLs + +Combine multiple parameters in a single URL. + +### GitHub API with Version and Endpoint + +```json +{ + "mcpServers": { + "github-api": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "-H", + "Accept: application/vnd.github.{api_version}+json", + "https://api.github.com/{endpoint}" + ] + } + } +} +``` + +**Usage:** "Fetch users/octocat with api_version: v3" + +### RESTful API with Dynamic Paths + +```json +{ + "mcpServers": { + "rest-api": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "-X", + "{method}", + "https://api.example.com/{version}/{resource}/{id}" + ] + } + } +} +``` + +**Usage:** "Call GET on v1/users/123" + +## Environment-Based Configuration + +Use environment variables for sensitive data. + +### API with Token + +```json +{ + "mcpServers": { + "secure-api": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-H", + "Authorization: Bearer ${API_TOKEN}", + "https://api.example.com/{endpoint}" + ], + "env": { + "API_TOKEN": "your-token-here" + } + } + } +} +``` + +**Security Note:** Store tokens in environment files, not in the config itself. + +### Database Query with Credentials + +```json +{ + "mcpServers": { + "db-query": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "psql", + "-h", + "${DB_HOST}", + "-U", + "${DB_USER}", + "-d", + "${DB_NAME}", + "-c", + "{query}" + ], + "env": { + "DB_HOST": "localhost", + "DB_USER": "admin", + "DB_NAME": "mydb", + "PGPASSWORD": "secret" + } + } + } +} +``` + +## Complex Git Operations + +Advanced git workflows. + +### Git Commit with Message + +```json +{ + "mcpServers": { + "git-commit": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo}", + "commit", + "[--all]", + "-m", + "{message}" + ] + } + } +} +``` + +**Usage:** "Commit changes in /path/to/repo with message: 'Fix bug'" + +### Git Push with Branch + +```json +{ + "mcpServers": { + "git-push": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo}", + "push", + "[--force]", + "{remote}", + "{branch}" + ] + } + } +} +``` + +**Usage:** "Push repo /path/to/repo to origin main" + +### Git Cherry-pick + +```json +{ + "mcpServers": { + "git-cherry-pick": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo}", + "cherry-pick", + "{commits...}" + ] + } + } +} +``` + +**Usage:** "Cherry-pick commits: abc123, def456 in /path/to/repo" + +## Docker Compose + +Manage multi-container applications. + +### Docker Compose Up + +```json +{ + "mcpServers": { + "compose-up": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker-compose", + "-f", + "{compose_file}", + "up", + "[--detach]", + "[services...]" + ] + } + } +} +``` + +**Usage:** "Start services web, db from docker-compose.yml with detach: true" + +### Docker Compose Logs + +```json +{ + "mcpServers": { + "compose-logs": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker-compose", + "-f", + "{compose_file}", + "logs", + "[--tail {lines}]", + "[--follow]", + "[service]" + ] + } + } +} +``` + +**Usage:** "Show logs for service web with lines: 100" + +## Data Processing Pipelines + +Complex command chains. + +### JSON Processing + +```json +{ + "mcpServers": { + "process-json": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "sh", + "-c", + "curl -s {url} | jq '{filter}'" + ] + } + } +} +``` + +**Usage:** "Process JSON from https://api.example.com/data with filter: '.results[]'" + +### Log Analysis + +```json +{ + "mcpServers": { + "analyze-logs": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "sh", + "-c", + "grep '{pattern}' {log_file} | wc -l" + ] + } + } +} +``` + +**Usage:** "Count errors in /var/log/app.log" + +## File Synchronization + +### Rsync with Options + +```json +{ + "mcpServers": { + "rsync": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "rsync", + "-avz", + "[--delete]", + "[--dry-run]", + "{source}", + "{destination}" + ] + } + } +} +``` + +**Usage:** "Sync /source/ to /dest/ with delete: true, dry_run: true" + +### SCP File Transfer + +```json +{ + "mcpServers": { + "scp": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "scp", + "[--recursive]", + "{source}", + "{user}@{host}:{destination}" + ] + } + } +} +``` + +**Usage:** "Copy file.txt to user@server.com:/tmp/" + +## System Monitoring + +### Disk Usage + +```json +{ + "mcpServers": { + "disk-usage": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "du", + "-sh", + "{path}" + ] + } + } +} +``` + +**Usage:** "Check disk usage of /var/log" + +### Process Monitoring + +```json +{ + "mcpServers": { + "ps-grep": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "sh", + "-c", + "ps aux | grep '{process}'" + ] + } + } +} +``` + +**Usage:** "Find processes matching 'node'" + +### Network Connections + +```json +{ + "mcpServers": { + "netstat": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "netstat", + "-an", + "|", + "grep", + "{port}" + ] + } + } +} +``` + +**Usage:** "Check connections on port 8080" + +## Build and Deploy + +### Maven Build + +```json +{ + "mcpServers": { + "maven": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "mvn", + "{goals...}", + "[--file {pom}]" + ] + } + } +} +``` + +**Usage:** "Run maven with goals: clean, install" + +### Gradle Build + +```json +{ + "mcpServers": { + "gradle": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "gradle", + "{tasks...}" + ] + } + } +} +``` + +**Usage:** "Run gradle with tasks: clean, build" + +### Make + +```json +{ + "mcpServers": { + "make": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "make", + "[--directory {dir}]", + "{target}" + ] + } + } +} +``` + +**Usage:** "Make target all in directory /path/to/project" + +## Testing Tools + +### Jest with Coverage + +```json +{ + "mcpServers": { + "jest": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "jest", + "[--coverage]", + "[--watch]", + "[pattern]" + ] + } + } +} +``` + +**Usage:** "Run jest with coverage: true, pattern: user.test.ts" + +### Pytest + +```json +{ + "mcpServers": { + "pytest": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "pytest", + "[--verbose]", + "[--coverage]", + "{tests...}" + ] + } + } +} +``` + +**Usage:** "Run pytest on tests: test_user.py, test_auth.py with verbose: true" + +## Code Quality + +### ESLint + +```json +{ + "mcpServers": { + "eslint": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "eslint", + "[--fix]", + "{files...}" + ] + } + } +} +``` + +**Usage:** "Lint src/main.ts with fix: true" + +### Prettier + +```json +{ + "mcpServers": { + "prettier": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "prettier", + "[--write]", + "{files...}" + ] + } + } +} +``` + +**Usage:** "Format files: src/*.ts with write: true" + +### TypeScript Compiler + +```json +{ + "mcpServers": { + "tsc": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "tsc", + "[--noEmit]", + "[--project {tsconfig}]" + ] + } + } +} +``` + +**Usage:** "Type-check with noEmit: true" + +## Database Operations + +### PostgreSQL Query + +```json +{ + "mcpServers": { + "psql": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "psql", + "-h", + "{host}", + "-d", + "{database}", + "-c", + "{query}" + ] + } + } +} +``` + +**Usage:** "Query database mydb on localhost: SELECT * FROM users" + +### MySQL Query + +```json +{ + "mcpServers": { + "mysql": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "mysql", + "-h", + "{host}", + "-D", + "{database}", + "-e", + "{query}" + ] + } + } +} +``` + +**Usage:** "Query database mydb: SELECT COUNT(*) FROM users" + +### Redis Commands + +```json +{ + "mcpServers": { + "redis": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "redis-cli", + "-h", + "{host}", + "{command...}" + ] + } + } +} +``` + +**Usage:** "Run redis command GET user:123 on localhost" + +## Cloud CLIs + +### AWS CLI + +```json +{ + "mcpServers": { + "aws": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "aws", + "{service}", + "{command}", + "[args...]" + ] + } + } +} +``` + +**Usage:** "Run AWS s3 ls with args: s3://my-bucket" + +### Google Cloud + +```json +{ + "mcpServers": { + "gcloud": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "gcloud", + "{service}", + "{command}", + "[args...]" + ] + } + } +} +``` + +**Usage:** "Run gcloud compute instances list" + +### Kubernetes + +```json +{ + "mcpServers": { + "kubectl": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "kubectl", + "{command}", + "[args...]" + ] + } + } +} +``` + +**Usage:** "Run kubectl get pods with args: -n, production" + +## Custom Scripts + +### Shell Script Wrapper + +```json +{ + "mcpServers": { + "deploy": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "/path/to/deploy.sh", + "{environment}", + "[--dry-run]" + ] + } + } +} +``` + +**Usage:** "Deploy to production with dry_run: true" + +### Python Script + +```json +{ + "mcpServers": { + "analyze": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "python3", + "/path/to/analyze.py", + "--input", + "{input_file}", + "--output", + "{output_file}", + "[--verbose]" + ] + } + } +} +``` + +**Usage:** "Analyze data.csv output to results.json with verbose: true" + +## Working Directory Context + +### Execute in Specific Directory + +```json +{ + "mcpServers": { + "build-project": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "sh", + "-c", + "cd {project_dir} && npm run build" + ] + } + } +} +``` + +**Usage:** "Build project in /path/to/project" + +## Debugging Complex Tools + +### Full Debug Configuration + +```json +{ + "mcpServers": { + "debug-tool": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/studio-debug.log", + "your-command", + "{args...}" + ] + } + } +} +``` + +Check `/tmp/studio-debug.log` for detailed execution logs. + +## Best Practices + +### 1. Parameter Validation + +Let commands handle validation: + +```json +{ + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "--fail", + "{url}" + ] +} +``` + +The `--fail` flag makes curl return errors for HTTP errors. + +### 2. Error Handling + +Use command flags for better errors: + +```json +{ + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo}", + "status", + "--porcelain" + ] +} +``` + +`--porcelain` gives machine-readable output. + +### 3. Idempotent Operations + +Prefer commands that can run multiple times: + +```json +{ + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "mkdir", + "-p", + "{directory}" + ] +} +``` + +`-p` won't error if directory exists. + +### 4. Descriptive Tool Names + +Use clear, descriptive names: + +```json +// Good +"git-commit-all" +"docker-compose-up" +"npm-build-production" + +// Less clear +"gc" +"dup" +"nb" +``` + +### 5. Document Parameters + +Always add descriptions: + +```json +{ + "args": [ + "-y", + "@studio-mcp/studio", + "command", + "{param # What this parameter does}" + ] +} +``` + +## Troubleshooting Advanced Tools + +### Shell Escaping Issues + +When using `sh -c`, escape carefully: + +```json +{ + "args": [ + "-y", + "@studio-mcp/studio", + "sh", + "-c", + "echo '{message}' | tr a-z A-Z" + ] +} +``` + +### Complex Command Chains + +Test each part separately first: + +```bash +# Test individually +curl -s https://api.example.com/data +jq '.results[]' data.json + +# Then combine +sh -c "curl -s https://api.example.com/data | jq '.results[]'" +``` + +### Debugging Pipeline Failures + +Add debug at each stage: + +```json +{ + "args": [ + "-y", + "@studio-mcp/studio", + "sh", + "-c", + "set -x && curl -s {url} | jq '{filter}'" + ] +} +``` + +`set -x` shows each command as it executes. + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Master all syntax features +- [Debugging](/guide/debugging) - Troubleshoot complex issues +- [Architecture](/reference/architecture) - Understand internals diff --git a/docs/examples/basic.md b/docs/examples/basic.md new file mode 100644 index 0000000..54d0261 --- /dev/null +++ b/docs/examples/basic.md @@ -0,0 +1,615 @@ +# Basic Examples + +This guide provides simple, practical examples to get you started with Studio MCP. + +## Echo Tool + +The simplest possible tool - just echo text back. + +### Configuration + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + } + } +} +``` + +### Usage + +"Use the echo tool to say 'Hello, World!'" + +### Output + +``` +Hello, World! +``` + +## Date and Time + +Get the current date and time. + +### Configuration + +```json +{ + "mcpServers": { + "date": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "date"] + } + } +} +``` + +### Usage + +"What's the current date and time?" + +### Output + +``` +Mon Jan 15 14:23:45 PST 2025 +``` + +## Weather Check + +Check the weather using wttr.in. + +### Configuration + +```json +{ + "mcpServers": { + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "wttr.in/{city}?format=3" + ] + } + } +} +``` + +### Usage + +"Check the weather in London" + +### Output + +``` +London: ☁️ +7°C +``` + +## Text-to-Speech (macOS) + +Make your computer speak text aloud. + +### Configuration + +```json +{ + "mcpServers": { + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech # A short phrase to speak out loud}" + ] + } + } +} +``` + +### Usage + +"Use the speak tool to say 'Hello from Studio MCP'" + +### Result + +Your computer speaks the text using the Samantha voice. + +## File Reading + +Read the contents of a file. + +### Configuration + +```json +{ + "mcpServers": { + "read-file": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "cat", + "{file_path # Path to the file to read}" + ] + } + } +} +``` + +### Usage + +"Read the file at /tmp/test.txt" + +### Output + +``` +Contents of the file... +``` + +## Directory Listing + +List files in a directory. + +### Configuration + +```json +{ + "mcpServers": { + "list-files": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "ls", + "-la", + "{directory # Directory path}" + ] + } + } +} +``` + +### Usage + +"List files in /tmp" + +### Output + +``` +total 8 +drwxr-xr-x 3 user wheel 96 Jan 15 14:23 . +drwxr-xr-x 12 user wheel 384 Jan 15 14:23 .. +-rw-r--r-- 1 user wheel 42 Jan 15 14:23 test.txt +``` + +## Command with Optional Arguments + +Echo with optional name parameter. + +### Configuration + +```json +{ + "mcpServers": { + "greet": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "Hello", + "[name]" + ] + } + } +} +``` + +### Usage 1: With name + +"Use greet with name: Alice" + +**Output:** +``` +Hello Alice +``` + +### Usage 2: Without name + +"Use greet without any name" + +**Output:** +``` +Hello +``` + +## Command with Boolean Flags + +List files with optional flags. + +### Configuration + +```json +{ + "mcpServers": { + "ls": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "ls", + "[--all]", + "[--long]", + "{path}" + ] + } + } +} +``` + +### Usage 1: With all flag + +"Use ls with path /tmp and all: true" + +**Output:** +``` +. .. .hidden-file test.txt +``` + +### Usage 2: With both flags + +"Use ls with path /tmp, all: true, and long: true" + +**Output:** +``` +total 8 +drwxr-xr-x 3 user wheel 96 Jan 15 14:23 . +drwxr-xr-x 12 user wheel 384 Jan 15 14:23 .. +-rw-r--r-- 1 user wheel 0 Jan 15 14:23 .hidden-file +-rw-r--r-- 1 user wheel 42 Jan 15 14:23 test.txt +``` + +## Command with Array Arguments + +Concatenate multiple files. + +### Configuration + +```json +{ + "mcpServers": { + "concat": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "cat", + "{files... # List of files to concatenate}" + ] + } + } +} +``` + +### Usage + +"Use concat with files: /tmp/file1.txt, /tmp/file2.txt" + +### Output + +``` +Contents of file1.txt +Contents of file2.txt +``` + +## GitHub API Access + +Fetch data from GitHub's API. + +### Configuration + +```json +{ + "mcpServers": { + "github-api": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "https://api.github.com/{endpoint}" + ] + } + } +} +``` + +### Usage + +"Use github-api with endpoint: users/octocat" + +### Output + +```json +{ + "login": "octocat", + "id": 583231, + "name": "The Octocat", + "bio": null, + ... +} +``` + +## URL Shortener Check + +Check where a short URL redirects. + +### Configuration + +```json +{ + "mcpServers": { + "check-redirect": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-I", + "-s", + "{url}" + ] + } + } +} +``` + +### Usage + +"Check where https://bit.ly/example redirects" + +### Output + +``` +HTTP/2 301 +location: https://example.com +... +``` + +## Calculator + +Perform basic arithmetic. + +### Configuration + +```json +{ + "mcpServers": { + "calc": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "bc", + "-l" + ] + } + } +} +``` + +### Note + +This requires piping input, which is more complex. See [Advanced Examples](/examples/advanced) for calculator implementations. + +## System Information + +Get system information. + +### Configuration (macOS/Linux) + +```json +{ + "mcpServers": { + "sysinfo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "uname", + "-a" + ] + } + } +} +``` + +### Usage + +"What's the system information?" + +### Output + +``` +Darwin MacBook.local 21.6.0 Darwin Kernel Version 21.6.0 x86_64 +``` + +## Find Files + +Search for files by name. + +### Configuration + +```json +{ + "mcpServers": { + "find-files": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "find", + "{directory}", + "-name", + "{pattern}" + ] + } + } +} +``` + +### Usage + +"Find files in /tmp matching *.txt" + +### Output + +``` +/tmp/file1.txt +/tmp/subdir/file2.txt +/tmp/test.txt +``` + +## Word Count + +Count words in a file. + +### Configuration + +```json +{ + "mcpServers": { + "word-count": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "wc", + "-w", + "{file}" + ] + } + } +} +``` + +### Usage + +"Count words in /tmp/document.txt" + +### Output + +``` + 1234 /tmp/document.txt +``` + +## Common Patterns + +### Pattern 1: Simple Command + +No parameters needed: + +```json +{ + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "date"] +} +``` + +### Pattern 2: Required Parameter + +One required string: + +```json +{ + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{message}"] +} +``` + +### Pattern 3: Optional Parameter + +One optional string: + +```json +{ + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "Hello", "[name]"] +} +``` + +### Pattern 4: Multiple Parameters + +Mix of required and optional: + +```json +{ + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "[--verbose]", + "{url}" + ] +} +``` + +### Pattern 5: Array Parameter + +Variable number of arguments: + +```json +{ + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "cat", "{files...}"] +} +``` + +## Testing Your Tools + +### Command Line Testing + +Test tools before adding to MCP clients: + +```bash +# Test basic execution +npx -y @studio-mcp/studio echo "{message}" + +# Test with MCP Inspector +npm install -g @modelcontextprotocol/inspector +mcp-inspector npx -y @studio-mcp/studio echo "{message}" +``` + +### Debug Mode + +Add debug logging to troubleshoot: + +```json +{ + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/tool.log", + "echo", + "{message}" + ] +} +``` + +## Next Steps + +- [Common Tools](/examples/common-tools) - Git, npm, docker examples +- [Advanced Examples](/examples/advanced) - Complex use cases +- [Template Syntax](/reference/template-syntax) - Full syntax reference diff --git a/docs/examples/common-tools.md b/docs/examples/common-tools.md new file mode 100644 index 0000000..eeb35d2 --- /dev/null +++ b/docs/examples/common-tools.md @@ -0,0 +1,798 @@ +# Common Tools + +This guide shows how to integrate popular development tools with Studio MCP. + +## Git + +### Git Status + +Check repository status. + +```json +{ + "mcpServers": { + "git-status": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo_path}", + "status", + "[--short]" + ] + } + } +} +``` + +**Usage:** "Check git status of /path/to/repo with short: true" + +### Git Log + +View commit history. + +```json +{ + "mcpServers": { + "git-log": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo_path}", + "log", + "--oneline", + "-n", + "{count # Number of commits}" + ] + } + } +} +``` + +**Usage:** "Show last 10 commits from /path/to/repo" + +### Git Diff + +Show changes in repository. + +```json +{ + "mcpServers": { + "git-diff": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo_path}", + "diff", + "[file]" + ] + } + } +} +``` + +**Usage:** "Show diff for file src/main.ts in /path/to/repo" + +### Git Clone + +Clone a repository. + +```json +{ + "mcpServers": { + "git-clone": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "clone", + "{url}", + "[directory]" + ] + } + } +} +``` + +**Usage:** "Clone https://github.com/user/repo.git" + +### Git Branch + +List or manage branches. + +```json +{ + "mcpServers": { + "git-branch": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo_path}", + "branch", + "[--all]" + ] + } + } +} +``` + +**Usage:** "List all branches in /path/to/repo" + +### Flexible Git + +General-purpose git tool with variable arguments. + +```json +{ + "mcpServers": { + "git": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "[args... # Git command and arguments]" + ] + } + } +} +``` + +**Usage:** "Run git with args: status, --short" + +## npm + +### npm Install + +Install packages. + +```json +{ + "mcpServers": { + "npm-install": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "install", + "{package}" + ] + } + } +} +``` + +**Usage:** "Install package lodash" + +### npm Search + +Search for packages. + +```json +{ + "mcpServers": { + "npm-search": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "search", + "{query}" + ] + } + } +} +``` + +**Usage:** "Search npm for react packages" + +### npm Run Script + +Run package.json scripts. + +```json +{ + "mcpServers": { + "npm-run": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "run", + "{script # Script name from package.json}" + ] + } + } +} +``` + +**Usage:** "Run script: build" + +### npm Info + +Get package information. + +```json +{ + "mcpServers": { + "npm-info": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "info", + "{package}", + "[field]" + ] + } + } +} +``` + +**Usage:** "Get info for package react, field: version" + +### npm List + +List installed packages. + +```json +{ + "mcpServers": { + "npm-list": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "list", + "[--depth {depth}]" + ] + } + } +} +``` + +**Usage:** "List packages with depth: 0" + +## Docker + +### Docker PS + +List containers. + +```json +{ + "mcpServers": { + "docker-ps": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker", + "ps", + "[--all]" + ] + } + } +} +``` + +**Usage:** "List all docker containers" + +### Docker Images + +List images. + +```json +{ + "mcpServers": { + "docker-images": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker", + "images" + ] + } + } +} +``` + +**Usage:** "Show docker images" + +### Docker Logs + +View container logs. + +```json +{ + "mcpServers": { + "docker-logs": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker", + "logs", + "[--tail {lines}]", + "{container}" + ] + } + } +} +``` + +**Usage:** "Show logs for container my-app with lines: 100" + +### Docker Exec + +Execute command in container. + +```json +{ + "mcpServers": { + "docker-exec": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker", + "exec", + "{container}", + "{command...}" + ] + } + } +} +``` + +**Usage:** "Execute in container my-app: ls, -la, /app" + +## curl + +### Basic GET Request + +```json +{ + "mcpServers": { + "curl-get": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "{url}" + ] + } + } +} +``` + +**Usage:** "Fetch https://api.github.com/users/octocat" + +### POST Request + +```json +{ + "mcpServers": { + "curl-post": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-X", + "POST", + "-H", + "Content-Type: application/json", + "-d", + "{data}", + "{url}" + ] + } + } +} +``` + +**Usage:** "Post to https://api.example.com/data with data: {\"key\":\"value\"}" + +### Custom Headers + +```json +{ + "mcpServers": { + "curl-auth": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-H", + "Authorization: Bearer {token}", + "{url}" + ] + } + } +} +``` + +**Usage:** "Fetch https://api.example.com/protected with token: abc123" + +### Download File + +```json +{ + "mcpServers": { + "curl-download": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-o", + "{output_file}", + "{url}" + ] + } + } +} +``` + +**Usage:** "Download https://example.com/file.zip to /tmp/file.zip" + +## Python + +### Run Python Script + +```json +{ + "mcpServers": { + "python-run": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "python3", + "{script_path}", + "[args...]" + ] + } + } +} +``` + +**Usage:** "Run script.py with args: --verbose, input.txt" + +### Python One-Liner + +```json +{ + "mcpServers": { + "python-eval": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "python3", + "-c", + "{code}" + ] + } + } +} +``` + +**Usage:** "Execute python code: print(2 + 2)" + +### pip Install + +```json +{ + "mcpServers": { + "pip-install": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "pip3", + "install", + "{package}" + ] + } + } +} +``` + +**Usage:** "Install package requests" + +## Grep + +### Search Files + +```json +{ + "mcpServers": { + "grep": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "grep", + "[--ignore-case]", + "{pattern}", + "{files...}" + ] + } + } +} +``` + +**Usage:** "Search for 'TODO' in files: src/main.ts, src/utils.ts" + +### Recursive Search + +```json +{ + "mcpServers": { + "grep-recursive": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "grep", + "-r", + "[--ignore-case]", + "{pattern}", + "{directory}" + ] + } + } +} +``` + +**Usage:** "Recursively search for 'function' in directory: src/" + +## Tar + +### Create Archive + +```json +{ + "mcpServers": { + "tar-create": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "tar", + "-czf", + "{archive_name}", + "{files...}" + ] + } + } +} +``` + +**Usage:** "Create archive backup.tar.gz with files: file1.txt, file2.txt" + +### Extract Archive + +```json +{ + "mcpServers": { + "tar-extract": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "tar", + "-xzf", + "{archive}", + "[--directory {dir}]" + ] + } + } +} +``` + +**Usage:** "Extract backup.tar.gz to directory: /tmp/restore" + +### List Archive Contents + +```json +{ + "mcpServers": { + "tar-list": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "tar", + "-tzf", + "{archive}" + ] + } + } +} +``` + +**Usage:** "List contents of backup.tar.gz" + +## jq + +### Parse JSON + +```json +{ + "mcpServers": { + "jq-parse": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "jq", + "{filter}", + "{file}" + ] + } + } +} +``` + +**Usage:** "Parse data.json with filter: '.users[0].name'" + +### Format JSON + +```json +{ + "mcpServers": { + "jq-format": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "jq", + ".", + "{file}" + ] + } + } +} +``` + +**Usage:** "Format file data.json" + +## sed + +### Replace Text + +```json +{ + "mcpServers": { + "sed-replace": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "sed", + "s/{pattern}/{replacement}/g", + "{file}" + ] + } + } +} +``` + +**Usage:** "Replace 'foo' with 'bar' in file.txt" + +## awk + +### Extract Columns + +```json +{ + "mcpServers": { + "awk-column": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "awk", + "{'{print $'}{column}{'}'}", + "{file}" + ] + } + } +} +``` + +**Usage:** "Extract column 2 from data.txt" + +## Complete Development Toolkit + +A comprehensive configuration with common tools: + +```json +{ + "mcpServers": { + "git-status": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo}", + "status", + "[--short]" + ] + }, + "npm-run": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "run", + "{script}" + ] + }, + "docker-ps": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "docker", + "ps", + "[--all]" + ] + }, + "curl-api": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "{url}" + ] + }, + "grep-search": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "grep", + "-r", + "{pattern}", + "{directory}" + ] + } + } +} +``` + +## Next Steps + +- [Advanced Examples](/examples/advanced) - Complex use cases +- [Template Syntax](/reference/template-syntax) - Full syntax reference +- [Debugging](/guide/debugging) - Troubleshooting tools diff --git a/docs/guide/config-claude.md b/docs/guide/config-claude.md new file mode 100644 index 0000000..f942b6c --- /dev/null +++ b/docs/guide/config-claude.md @@ -0,0 +1,344 @@ +# Configuring Claude Desktop + +Claude Desktop supports MCP servers through a JSON configuration file. This guide shows you how to add Studio MCP tools to Claude Desktop. + +## Configuration File Location + +The configuration file location varies by platform: + +**macOS:** +``` +~/Library/Application Support/Claude/claude_desktop_config.json +``` + +**Windows:** +``` +%APPDATA%\Claude\claude_desktop_config.json +``` + +## Basic Configuration + +Create or edit the configuration file with this structure: + +```json +{ + "mcpServers": { + "tool-name": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "your-command", + "{parameters}" + ] + } + } +} +``` + +## Simple Example + +Add an echo tool: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{message # The text to echo}" + ] + } + } +} +``` + +After saving, restart Claude Desktop to load the new configuration. + +## Multiple Tools + +Add multiple tools to the same configuration: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{text}" + ] + }, + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech # A concise message to say out loud}" + ] + }, + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "wttr.in/{city}?format=3" + ] + } + } +} +``` + +## Common Examples + +### Text-to-Speech (macOS) + +```json +{ + "mcpServers": { + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech # A short phrase to speak out loud}" + ] + } + } +} +``` + +**Usage:** "Use the speak tool to say hello" + +### Curl with API Endpoints + +```json +{ + "mcpServers": { + "api-get": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "https://api.github.com/{endpoint}" + ] + } + } +} +``` + +**Usage:** "Use api-get to fetch users/octocat" + +### Git Commands + +```json +{ + "mcpServers": { + "git": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "[args...]" + ] + } + } +} +``` + +**Usage:** "Use git tool with args: status, --short" + +### Date and Time + +```json +{ + "mcpServers": { + "date": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "date", + "[format]" + ] + } + } +} +``` + +**Usage:** "What's the current date?" or "Use date with format: +%Y-%m-%d" + +## Using Global Installation + +If you've installed Studio globally, you can use it directly: + +```json +{ + "mcpServers": { + "echo": { + "command": "studio", + "args": [ + "echo", + "{message}" + ] + } + } +} +``` + +**Note:** This requires `npm install -g @studio-mcp/studio` first. + +## Debugging Configuration + +Add debug flags to troubleshoot issues: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/studio-echo.log", + "echo", + "{message}" + ] + } + } +} +``` + +Check the log file at `/tmp/studio-echo.log` for debug output. + +## Environment Variables + +Set environment variables for your tools: + +```json +{ + "mcpServers": { + "api-call": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-H", + "Authorization: Bearer ${API_TOKEN}", + "https://api.example.com/{endpoint}" + ], + "env": { + "API_TOKEN": "your-token-here" + } + } + } +} +``` + +**Security Note:** Never commit API tokens to version control. Consider using a separate file or environment variable manager. + +## Testing Configuration + +After editing the configuration: + +1. **Save the file** - Ensure JSON is valid (no trailing commas!) +2. **Restart Claude Desktop** - Completely quit and reopen +3. **Check the Tools** - Look for the hammer icon in Claude Desktop +4. **Test a tool** - Ask Claude to use your tool + +## Troubleshooting + +### Tool not appearing + +1. Check JSON syntax - Use a JSON validator +2. Ensure Claude Desktop was fully restarted +3. Check the configuration file path is correct +4. Verify npx works: `npx -y @studio-mcp/studio --version` + +### Tool fails to execute + +1. Add `--debug` and `--log` flags to see errors +2. Test the command directly in terminal +3. Check file permissions and paths +4. Verify the command is available on your system + +### Invalid JSON errors + +Common mistakes: +- Trailing commas (not allowed in JSON) +- Missing quotes around strings +- Unescaped backslashes in Windows paths + +Use a JSON validator or editor with JSON support. + +## Complete Example + +Here's a comprehensive configuration with multiple useful tools: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + }, + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech # Short phrase to speak}" + ] + }, + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "wttr.in/{city}?format=3" + ] + }, + "git-status": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo_path}", + "status", + "[--short]" + ] + } + } +} +``` + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Learn advanced template features +- [Examples](/examples/basic) - More tool examples +- [Debugging](/guide/debugging) - Troubleshooting guide diff --git a/docs/guide/config-cursor.md b/docs/guide/config-cursor.md new file mode 100644 index 0000000..8e9ca31 --- /dev/null +++ b/docs/guide/config-cursor.md @@ -0,0 +1,371 @@ +# Configuring Cursor + +Cursor is an AI-powered code editor with MCP support. This guide shows you how to add Studio MCP tools to Cursor. + +## Configuration File Location + +Cursor uses a different configuration file than Claude Desktop: + +**All Platforms:** +``` +~/.cursor/mcp.json +``` + +**Windows:** +``` +%USERPROFILE%\.cursor\mcp.json +``` + +## Important: Cursor Limitations + +Cursor currently has a bug that prevents spaces in argument descriptions. You must: + +1. **Use underscores instead of spaces** in descriptions +2. **Avoid spaces in the template syntax** + +This is a known issue with Cursor's MCP implementation. + +## Basic Configuration + +Create or edit `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "tool-name": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "your-command", + "{parameters}" + ] + } + } +} +``` + +## Simple Example + +Add an echo tool (note: no spaces in description): + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{message#text_to_echo}" + ] + } + } +} +``` + +**Important:** Notice `{message#text_to_echo}` uses underscores, not spaces. + +## Correct vs Incorrect + +### ❌ Incorrect (will fail in Cursor): + +```json +{ + "mcpServers": { + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "{speech # A message to say}" + ] + } + } +} +``` + +The spaces in `"# A message to say"` will cause errors. + +### ✅ Correct (works in Cursor): + +```json +{ + "mcpServers": { + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "{speech#message_to_say}" + ] + } + } +} +``` + +Use underscores or omit the description entirely. + +## Common Examples + +### Echo Tool + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{text#message_to_echo}" + ] + } + } +} +``` + +### Text-to-Speech (macOS) + +```json +{ + "mcpServers": { + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech#text_to_speak}" + ] + } + } +} +``` + +### Weather Check + +```json +{ + "mcpServers": { + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "wttr.in/{city}?format=3" + ] + } + } +} +``` + +### Git Commands + +```json +{ + "mcpServers": { + "git": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "[args...]" + ] + } + } +} +``` + +### API Requests + +```json +{ + "mcpServers": { + "api-get": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "https://api.github.com/{endpoint#api_path}" + ] + } + } +} +``` + +## Multiple Tools + +Configure multiple tools in one file: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + }, + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "wttr.in/{city}?format=3" + ] + }, + "git": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "git", "[args...]"] + } + } +} +``` + +## Using Global Installation + +If you've installed Studio globally: + +```json +{ + "mcpServers": { + "echo": { + "command": "studio", + "args": ["echo", "{message}"] + } + } +} +``` + +Requires: `npm install -g @studio-mcp/studio` + +## Debugging in Cursor + +Add debug flags to troubleshoot: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/cursor-studio.log", + "echo", + "{message}" + ] + } + } +} +``` + +Check `/tmp/cursor-studio.log` for debug output. + +## Reloading Configuration + +After editing `~/.cursor/mcp.json`: + +1. **Save the file** +2. **Reload Cursor** - Use `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) +3. **Search for "Reload Window"** and execute +4. **Test the tool** - Ask Cursor's AI to use your tool + +## Troubleshooting + +### Tool not appearing + +1. Verify file location: `~/.cursor/mcp.json` +2. Check JSON syntax (no trailing commas) +3. Reload Cursor window +4. Check Cursor's developer console for errors + +### "Invalid argument" errors + +1. Remove spaces from descriptions +2. Use underscores: `{arg#like_this}` not `{arg # like this}` +3. Test the command in terminal first + +### Command not found + +1. Verify npx is available: `npx --version` +2. Test Studio: `npx -y @studio-mcp/studio --version` +3. Use full path to npx if needed + +## Complete Example + +A comprehensive Cursor configuration: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + }, + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech#text_to_speak}" + ] + }, + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "wttr.in/{city}?format=3" + ] + }, + "git": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "git", "[args...]"] + }, + "npm-search": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "search", + "{package_name}" + ] + } + } +} +``` + +## Cursor-Specific Tips + +1. **Keep descriptions short** - Use single words or underscores +2. **Test commands first** - Verify in terminal before adding to config +3. **Use simple tools** - Complex commands may not work well in Cursor +4. **Check logs** - Use `--log` flag for debugging +5. **Reload frequently** - Cursor sometimes needs a full reload + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Learn template features +- [Examples](/examples/basic) - More tool examples +- [Debugging](/guide/debugging) - Troubleshooting guide diff --git a/docs/guide/config-vscode.md b/docs/guide/config-vscode.md new file mode 100644 index 0000000..ef29013 --- /dev/null +++ b/docs/guide/config-vscode.md @@ -0,0 +1,466 @@ +# Configuring VSCode + +Visual Studio Code supports MCP through extensions and configuration. This guide shows you how to add Studio MCP tools to VSCode. + +## Prerequisites + +VSCode MCP support requires: +- VSCode version 1.85 or later +- An MCP-compatible extension (varies by implementation) + +Check with your specific MCP extension documentation for exact requirements. + +## Configuration File Location + +VSCode MCP configuration is typically in: + +**All Platforms:** +``` +.vscode/settings.json (workspace) +``` + +Or global settings: +``` +~/Library/Application Support/Code/User/settings.json (macOS) +%APPDATA%\Code\User\settings.json (Windows) +~/.config/Code/User/settings.json (Linux) +``` + +## Basic Configuration + +The exact configuration format depends on your MCP extension. Here's a common pattern: + +```json +{ + "mcp.servers": { + "tool-name": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "your-command", + "{parameters}" + ] + } + } +} +``` + +## Simple Example + +Add an echo tool: + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{message # What to echo}" + ] + } + } +} +``` + +## Common Examples + +### Echo Tool + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{text # Text to echo}" + ] + } + } +} +``` + +### Git Commands + +```json +{ + "mcp.servers": { + "git": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "[args...]" + ] + } + } +} +``` + +### File Operations + +```json +{ + "mcp.servers": { + "cat": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "cat", + "{file_path # Path to file}" + ] + } + } +} +``` + +### Curl for API Calls + +```json +{ + "mcp.servers": { + "api-request": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "https://api.example.com/{endpoint}" + ] + } + } +} +``` + +### NPM Package Search + +```json +{ + "mcp.servers": { + "npm-search": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "search", + "{package}" + ] + } + } +} +``` + +## Workspace Configuration + +For project-specific tools, create `.vscode/settings.json` in your project: + +```json +{ + "mcp.servers": { + "project-build": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "run", + "{script # npm script name}" + ] + }, + "test": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "test", + "[file # test file path]" + ] + } + } +} +``` + +## Using Global Installation + +If Studio is installed globally: + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "studio", + "args": ["echo", "{message}"] + } + } +} +``` + +Requires: `npm install -g @studio-mcp/studio` + +## Environment Variables + +Set environment variables for your tools: + +```json +{ + "mcp.servers": { + "api-call": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-H", + "Authorization: Bearer ${API_TOKEN}", + "https://api.example.com/{endpoint}" + ], + "env": { + "API_TOKEN": "your-token-here" + } + } + } +} +``` + +## Debugging Configuration + +Enable debug logging: + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "${workspaceFolder}/studio.log", + "echo", + "{message}" + ] + } + } +} +``` + +Use VSCode variables: +- `${workspaceFolder}` - Project root +- `${file}` - Current file path +- `${fileBasename}` - Current file name +- `${fileDirname}` - Current file directory + +## Multiple Tools Configuration + +A comprehensive VSCode setup: + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + }, + "git": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "git", "[args...]"] + }, + "curl": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "{url}" + ] + }, + "npm-run": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "run", + "{script}" + ] + } + } +} +``` + +## Reloading Configuration + +After editing settings: + +1. **Save settings.json** +2. **Reload window** - `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) +3. **Search "Developer: Reload Window"** +4. **Test the tool** - Try using your MCP tool + +## Troubleshooting + +### Tool not appearing + +1. Check the MCP extension is installed and enabled +2. Verify JSON syntax (no trailing commas) +3. Reload VSCode window +4. Check Output panel for errors + +### Command fails + +1. Test command in integrated terminal +2. Check file paths are correct +3. Verify npx is available: `npx --version` +4. Use absolute paths if needed + +### Permission errors + +1. Ensure execute permissions on scripts +2. On macOS/Linux, check file permissions +3. Use full paths to executables + +## VSCode-Specific Tips + +### Using Workspace Variables + +```json +{ + "mcp.servers": { + "lint-current-file": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "eslint", + "${file}" + ] + } + } +} +``` + +### Project-Specific Tools + +```json +{ + "mcp.servers": { + "build": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "run", + "build" + ], + "cwd": "${workspaceFolder}" + } + } +} +``` + +### Conditional Configuration + +Use VSCode's settings precedence: +1. Workspace settings (`.vscode/settings.json`) +2. User settings (global) + +This allows project-specific overrides. + +## Complete Example + +A full VSCode workspace configuration: + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + }, + "git-status": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "${workspaceFolder}", + "status" + ] + }, + "build": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "run", + "build" + ] + }, + "test": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "npm", + "test", + "[file]" + ] + }, + "curl": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "-s", + "{url}" + ] + } + } +} +``` + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Learn advanced template features +- [Examples](/examples/basic) - More tool examples +- [Debugging](/guide/debugging) - Troubleshooting guide diff --git a/docs/guide/debugging.md b/docs/guide/debugging.md new file mode 100644 index 0000000..d0a5483 --- /dev/null +++ b/docs/guide/debugging.md @@ -0,0 +1,425 @@ +# Debugging + +When your Studio MCP tools aren't working as expected, debugging helps identify the problem. This guide covers debugging techniques and common issues. + +## Debug Mode + +Studio provides built-in debug logging to help troubleshoot issues. + +### Enable Debug Output + +Add the `--debug` flag to enable debug logging: + +```bash +studio --debug echo "{message}" +``` + +This prints debug information to stderr, including: +- Template parsing details +- Generated JSON schema +- Parameter validation +- Command execution + +### Log to File + +For persistent logs, use the `--log` flag: + +```bash +studio --log /tmp/studio.log echo "{message}" +``` + +Or combine with debug: + +```bash +studio --debug --log /tmp/studio.log echo "{message}" +``` + +## Debugging in MCP Clients + +### Claude Desktop + +Add debug flags to your configuration: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/studio-echo.log", + "echo", + "{message}" + ] + } + } +} +``` + +Then check `/tmp/studio-echo.log` for debug output. + +**macOS Log Location:** +```bash +tail -f ~/Library/Application\ Support/Claude/logs/mcp*.log +``` + +### Cursor + +Add debug logging: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/cursor-studio.log", + "echo", + "{message}" + ] + } + } +} +``` + +### VSCode + +Use workspace folder for logs: + +```json +{ + "mcp.servers": { + "echo": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "${workspaceFolder}/.studio.log", + "echo", + "{message}" + ] + } + } +} +``` + +## Testing Commands Directly + +Before adding to MCP clients, test commands in the terminal: + +```bash +# Test basic execution +npx -y @studio-mcp/studio echo "{message}" + +# This starts an MCP server on stdio +# You won't see output directly, but you can test the server works +``` + +For interactive testing, use the MCP Inspector: + +```bash +npm install -g @modelcontextprotocol/inspector +mcp-inspector npx -y @studio-mcp/studio echo "{message}" +``` + +This opens a web interface to test your tool. + +## Common Issues + +### Issue: Tool not appearing in client + +**Symptoms:** +- Tool doesn't show up in Claude Desktop/Cursor +- No errors visible + +**Debugging steps:** + +1. Check JSON syntax: + ```bash + # Use a JSON validator + cat claude_desktop_config.json | jq . + ``` + +2. Verify configuration file location: + ```bash + # macOS Claude Desktop + cat ~/Library/Application\ Support/Claude/claude_desktop_config.json + + # Cursor + cat ~/.cursor/mcp.json + ``` + +3. Check client logs: + ```bash + # Claude Desktop (macOS) + ls -lt ~/Library/Application\ Support/Claude/logs/ + tail -f ~/Library/Application\ Support/Claude/logs/mcp*.log + ``` + +4. Restart the client completely + +### Issue: Command fails to execute + +**Symptoms:** +- Error messages in client +- Tool appears but doesn't work + +**Debugging steps:** + +1. Test the command directly: + ```bash + # Test without Studio + echo "Hello" + + # Test with Studio + npx -y @studio-mcp/studio --debug echo "{message}" + ``` + +2. Check command availability: + ```bash + which echo + which curl + which git + ``` + +3. Verify parameters: + ```bash + # Enable debug logging + studio --debug --log /tmp/debug.log echo "{message}" + + # Check the log + cat /tmp/debug.log + ``` + +4. Test with MCP Inspector: + ```bash + mcp-inspector npx -y @studio-mcp/studio echo "{message}" + ``` + +### Issue: Template parsing errors + +**Symptoms:** +- "Invalid template" errors +- Parameters not recognized + +**Debugging steps:** + +1. Check template syntax: + ```bash + # Required: {name} or {{name}} + studio echo "{message}" + + # Optional: [name] + studio echo "[message]" + + # Array: [name...] or {name...} + studio echo "[args...]" + ``` + +2. Verify quote escaping: + ```bash + # In JSON config, escape quotes + "args": ["echo", "{message}"] # Correct + ``` + +3. Test template parsing: + ```bash + studio --debug echo "{message}" + # Check output for template parsing details + ``` + +### Issue: Cursor spaces bug + +**Symptoms:** +- Errors with descriptions containing spaces +- Works in Claude but not Cursor + +**Solution:** + +Use underscores instead of spaces in Cursor: + +```json +// Claude Desktop (works) +"{message # A message to echo}" + +// Cursor (use this) +"{message#message_to_echo}" +``` + +### Issue: npx command not found + +**Symptoms:** +- "command not found: npx" +- Tool fails to start + +**Debugging steps:** + +1. Verify Node.js installation: + ```bash + node --version + npm --version + npx --version + ``` + +2. Check PATH: + ```bash + echo $PATH + which npx + ``` + +3. Use full path: + ```bash + # Find npx location + which npx + # Example: /usr/local/bin/npx + + # Use in config + "command": "/usr/local/bin/npx" + ``` + +4. Install globally instead: + ```bash + npm install -g @studio-mcp/studio + # Then use + "command": "studio" + ``` + +### Issue: Permission denied + +**Symptoms:** +- "EACCES" or "Permission denied" errors +- Command can't execute + +**Debugging steps:** + +1. Check file permissions: + ```bash + ls -la /path/to/script + chmod +x /path/to/script + ``` + +2. Verify user permissions: + ```bash + # Test as current user + echo "test" > /tmp/test.txt + ``` + +3. Check command permissions: + ```bash + which + ls -la $(which ) + ``` + +## Verbose Logging + +For maximum debugging information: + +```bash +studio --debug --log /tmp/studio-verbose.log echo "{message}" 2>&1 | tee /tmp/studio-stderr.log +``` + +This captures: +- Debug output to `/tmp/studio-verbose.log` +- Stderr to `/tmp/studio-stderr.log` +- Stdout (MCP protocol) to terminal + +## MCP Inspector + +The MCP Inspector is the best way to debug MCP tools: + +### Install + +```bash +npm install -g @modelcontextprotocol/inspector +``` + +### Use + +```bash +mcp-inspector npx -y @studio-mcp/studio echo "{message}" +``` + +This opens a web interface where you can: +- See the generated tool schema +- Test tool execution +- View input/output +- Check errors and logs + +### Example Session + +```bash +# Start inspector +mcp-inspector npx -y @studio-mcp/studio \ + --debug \ + --log /tmp/studio.log \ + curl "https://api.github.com/{endpoint}" + +# Open browser to http://localhost:5173 +# Test the tool with different endpoints +# Check debug logs in /tmp/studio.log +``` + +## Debugging Checklist + +When a tool isn't working: + +- [ ] Verify JSON syntax in config file +- [ ] Check command works in terminal +- [ ] Test with `--debug` flag +- [ ] Review log file with `--log` +- [ ] Use MCP Inspector +- [ ] Check client-specific logs +- [ ] Verify command is in PATH +- [ ] Test with simple example first +- [ ] Check for Cursor spaces bug +- [ ] Restart MCP client completely + +## Debug Log Example + +A typical debug log shows: + +``` +[DEBUG] Parsing template: echo "{message # text to echo}" +[DEBUG] Tokens: [ + { type: "text", value: "echo" }, + { type: "field", name: "message", description: "text to echo", required: true } +] +[DEBUG] Generated schema: { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "text to echo" + } + }, + "required": ["message"] +} +[DEBUG] Executing: echo "Hello, World!" +[DEBUG] Exit code: 0 +``` + +## Getting Help + +If you're still stuck: + +1. Check the [GitHub Issues](https://github.com/studio-mcp/studio/issues) +2. Create a minimal reproduction case +3. Include debug logs +4. Specify your platform and client +5. Share your configuration (sanitized) + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Verify template correctness +- [Examples](/examples/basic) - See working examples +- [Architecture](/reference/architecture) - Understand how Studio works diff --git a/docs/guide/development.md b/docs/guide/development.md new file mode 100644 index 0000000..505c1ca --- /dev/null +++ b/docs/guide/development.md @@ -0,0 +1,447 @@ +# Development + +This guide covers how to develop, test, and contribute to Studio MCP itself. + +## Setting Up Development Environment + +### Prerequisites + +- Node.js 18 or later +- Bun (recommended) or npm +- Git + +### Clone the Repository + +```bash +git clone https://github.com/studio-mcp/studio.git +cd studio +``` + +### Install Dependencies + +```bash +# Using bun (recommended) +bun install + +# Or using npm +npm install +``` + +### Project Structure + +``` +studio/ +├── src/ +│ ├── index.ts # Main entry point +│ ├── studio/ +│ │ ├── types.ts # Type definitions +│ │ ├── parse.ts # Template parsing +│ │ ├── schema.ts # JSON schema generation +│ │ └── render.ts # Command rendering +│ └── __tests__/ # Test files +├── package.json +├── tsconfig.json +└── README.md +``` + +## Development Commands + +### Build + +Compile TypeScript to JavaScript: + +```bash +bun run build +# or +npm run build +``` + +Output goes to `dist/` directory. + +### Run in Development Mode + +Run without building: + +```bash +bun run dev echo "{message}" +# or +npm run dev echo "{message}" +``` + +### Run Tests + +Execute the test suite: + +```bash +# Run all tests +bun run test + +# Watch mode +bun run test:watch + +# Specific test file +bun test src/__tests__/parse.test.ts +``` + +### Linting and Formatting + +```bash +# Lint code +bun run lint + +# Format code +bun run format +``` + +## Testing Your Changes + +### Unit Tests + +Studio uses Bun's built-in test runner. Create tests in `src/__tests__/`: + +```typescript +import { describe, test, expect } from 'bun:test' +import { parseTemplate } from '../studio/parse' + +describe('parseTemplate', () => { + test('parses required arguments', () => { + const template = parseTemplate(['echo', '{message}']) + expect(template.fields).toHaveLength(1) + expect(template.fields[0].name).toBe('message') + expect(template.fields[0].required).toBe(true) + }) +}) +``` + +### Integration Testing + +Test with MCP Inspector: + +```bash +# Install inspector +npm install -g @modelcontextprotocol/inspector + +# Run with dev build +bun run inspector:echo + +# Or custom command +mcp-inspector bun run dev echo "{message}" +``` + +### Manual Testing + +Test the built version: + +```bash +# Build first +bun run build + +# Test the built binary +node dist/index.js echo "{message}" +``` + +## Code Architecture + +### Template Parsing Flow + +``` +User Input → Tokenization → Field Extraction → Schema Generation → Command Execution +``` + +#### 1. Tokenization (src/studio/parse.ts) + +Converts command arguments into tokens: + +```typescript +// Input: ["echo", "{message}", "world"] +// Output: [ +// TextToken { value: "echo" }, +// FieldToken { name: "message", required: true }, +// TextToken { value: "world" } +// ] +``` + +#### 2. Schema Generation (src/studio/schema.ts) + +Creates JSON schema from tokens: + +```typescript +// Input: FieldToken { name: "message", required: true } +// Output: { +// type: "object", +// properties: { +// message: { type: "string" } +// }, +// required: ["message"] +// } +``` + +#### 3. Command Rendering (src/studio/render.ts) + +Builds final command with parameters: + +```typescript +// Input: template + { message: "Hello" } +// Output: ["echo", "Hello", "world"] +``` + +### Key Types + +From `src/studio/types.ts`: + +```typescript +interface Template { + args: Token[] + fields: FieldToken[] +} + +interface FieldToken { + kind: 'field' + name: string + description?: string + required: boolean + array: boolean + boolean: boolean +} + +interface TextToken { + kind: 'text' + value: string +} +``` + +## Adding New Features + +### Example: Adding a New Template Syntax + +1. **Update types** in `src/studio/types.ts` +2. **Add parsing logic** in `src/studio/parse.ts` +3. **Update schema generation** in `src/studio/schema.ts` +4. **Add rendering logic** in `src/studio/render.ts` +5. **Write tests** in `src/__tests__/` +6. **Update documentation** + +### Example: Adding a New CLI Flag + +1. **Update parseArgs()** in `src/index.ts` +2. **Add to help text** +3. **Implement functionality** +4. **Add tests** +5. **Update README** + +## Debugging Development + +### Enable Debug Logging + +```typescript +// In src/index.ts +const DEBUG = process.env.DEBUG === 'true' + +if (DEBUG) { + console.error('[DEBUG]', debugInfo) +} +``` + +Run with debug: + +```bash +DEBUG=true bun run dev echo "{message}" +``` + +### Use MCP Inspector + +The inspector is invaluable for development: + +```bash +# Run current dev build +mcp-inspector bun run dev echo "{message}" + +# Test specific scenarios +mcp-inspector bun run dev --debug --log /tmp/dev.log curl "{url}" +``` + +### Test with Real MCP Clients + +Create a dev configuration for Claude Desktop: + +```json +{ + "mcpServers": { + "studio-dev": { + "command": "bun", + "args": [ + "run", + "/path/to/studio/src/index.ts", + "--debug", + "--log", + "/tmp/studio-dev.log", + "echo", + "{message}" + ] + } + } +} +``` + +## Running Examples + +The repository includes example configurations: + +```bash +# Test with the example config +cat .mcp.json + +# Run with inspector +bun run inspector:echo +bun run inspector:git +``` + +## Contributing + +### Before Submitting + +1. **Run tests**: `bun run test` +2. **Check types**: `bun run build` +3. **Format code**: `bun run format` +4. **Update docs** if needed +5. **Add tests** for new features + +### Pull Request Process + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/amazing-feature` +3. Make your changes +4. Add tests +5. Commit: `git commit -m 'Add amazing feature'` +6. Push: `git push origin feature/amazing-feature` +7. Open a Pull Request + +### Commit Message Convention + +Use conventional commits: + +``` +feat: add support for regex patterns in templates +fix: handle empty array parameters correctly +docs: update template syntax reference +test: add tests for boolean flags +chore: update dependencies +``` + +## Publishing (Maintainers) + +### Version Bump + +```bash +# Patch (0.0.x) +npm version patch + +# Minor (0.x.0) +npm version minor + +# Major (x.0.0) +npm version major +``` + +### Build and Publish + +```bash +# Build +bun run build + +# Publish to npm +npm publish + +# Or with tag +npm publish --tag beta +``` + +### Release Checklist + +- [ ] Update version in package.json +- [ ] Update CHANGELOG.md +- [ ] Run full test suite +- [ ] Build successfully +- [ ] Test built package locally +- [ ] Create git tag +- [ ] Push to GitHub +- [ ] Publish to npm +- [ ] Create GitHub release + +## Development Tips + +### Quick Iteration + +Use watch mode for tests: + +```bash +bun run test:watch +``` + +### Test Multiple Scenarios + +Create a test script: + +```bash +#!/bin/bash +# test-scenarios.sh + +echo "Test 1: Required arg" +bun run dev echo "{message}" + +echo "Test 2: Optional arg" +bun run dev echo "[message]" + +echo "Test 3: Array arg" +bun run dev git "[args...]" +``` + +### Use Type Checking + +TypeScript helps catch errors early: + +```bash +# Check types without building +tsc --noEmit +``` + +### Debug with VSCode + +Create `.vscode/launch.json`: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Debug Studio", + "program": "${workspaceFolder}/src/index.ts", + "args": ["echo", "{message}"], + "runtimeExecutable": "bun", + "runtimeArgs": ["run"], + "console": "integratedTerminal" + } + ] +} +``` + +## Resources + +- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) +- [Bun Documentation](https://bun.sh/docs) +- [MCP Specification](https://modelcontextprotocol.io/) +- [Zod Documentation](https://zod.dev/) + +## Getting Help + +- GitHub Discussions for questions +- GitHub Issues for bugs +- Pull Requests for contributions + +## Next Steps + +- [Architecture Reference](/reference/architecture) - Deep dive into internals +- [Template Syntax](/reference/template-syntax) - Complete syntax reference +- [Examples](/examples/basic) - Real-world examples diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md new file mode 100644 index 0000000..5495230 --- /dev/null +++ b/docs/guide/getting-started.md @@ -0,0 +1,215 @@ +# Getting Started + +This guide will walk you through installing Studio MCP and creating your first MCP tool. + +## Prerequisites + +Studio MCP requires Node.js 18 or later. Check your version: + +```bash +node --version +``` + +## Installation + +You have two options for using Studio MCP: + +### Option 1: Use npx (Recommended) + +No installation required! Use `npx` to run Studio on demand: + +```bash +npx -y @studio-mcp/studio echo "{message}" +``` + +The `-y` flag automatically accepts the package installation. + +### Option 2: Global Installation + +Install Studio globally for faster execution: + +```bash +npm install -g @studio-mcp/studio +``` + +Then use it directly: + +```bash +studio echo "{message}" +``` + +## Your First Tool + +Let's create a simple echo tool that AI assistants can use. + +### Step 1: Test the Command + +First, test Studio from the command line to verify it works: + +```bash +npx -y @studio-mcp/studio echo "{message}" +``` + +This starts an MCP server that exposes the `echo` command with a `message` parameter. + +### Step 2: Add to MCP Client + +Now add it to your MCP client configuration. For Claude Desktop, edit: + +**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +**Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +Add this configuration: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "echo", + "{message}" + ] + } + } +} +``` + +### Step 3: Restart Claude Desktop + +Close and reopen Claude Desktop to load the new configuration. + +### Step 4: Use the Tool + +In Claude Desktop, you can now say: + +> "Use the echo tool to say 'Hello, World!'" + +Claude will invoke the tool and show you the output. + +## Understanding the Configuration + +Let's break down what each part does: + +```json +{ + "mcpServers": { + "echo": { // Server name (arbitrary) + "command": "npx", // How to run Studio + "args": [ + "-y", // Auto-accept npx install + "@studio-mcp/studio", // Package name + "echo", // CLI command to wrap + "{message}" // Template with parameters + ] + } + } +} +``` + +The template `"{message}"` tells Studio: +- Create a tool parameter called `message` +- The parameter is required (using `{}` not `[]`) +- The parameter is a string +- Pass it as an argument to `echo` + +## More Examples + +### Example 1: Text-to-Speech + +Make Claude speak out loud (macOS): + +```json +{ + "mcpServers": { + "speak": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "say", + "-v", + "Samantha", + "{speech # A short phrase to speak out loud}" + ] + } + } +} +``` + +Usage: "Use the speak tool to say hello" + +### Example 2: Weather Check + +Wrap curl to check weather: + +```json +{ + "mcpServers": { + "weather": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "curl", + "wttr.in/{city}?format=3" + ] + } + } +} +``` + +Usage: "Check the weather in London" + +### Example 3: Git Status + +Check git repository status: + +```json +{ + "mcpServers": { + "git-status": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "git", + "-C", + "{repo_path}", + "status" + ] + } + } +} +``` + +Usage: "Check the status of /path/to/repo" + +## Command Line Usage + +You can also run Studio directly for testing: + +```bash +# Basic syntax +studio [template args...] + +# With debugging +studio --debug echo "{message}" + +# Log to file +studio --log /tmp/studio.log curl "https://api.github.com/{endpoint}" + +# Stop flag parsing with -- +studio -- command --with-flags "{arg}" +``` + +## Next Steps + +Now that you have Studio working, explore: + +- [Template Syntax](/reference/template-syntax) - Learn all template features +- [Configuration Guides](/guide/config-claude) - Client-specific setup +- [Examples](/examples/basic) - More real-world examples +- [Debugging](/guide/debugging) - Troubleshoot issues diff --git a/docs/guide/installation.md b/docs/guide/installation.md new file mode 100644 index 0000000..8a8bd03 --- /dev/null +++ b/docs/guide/installation.md @@ -0,0 +1,299 @@ +# Installation + +Studio MCP can be installed globally, used via npx, or run from source for development. + +## Prerequisites + +- **Node.js**: Version 18 or later +- **npm**: Comes with Node.js (or use yarn, pnpm, bun) + +Check your versions: + +```bash +node --version # Should be v18.0.0 or higher +npm --version +``` + +## Installation Methods + +### Method 1: npx (No Installation) + +The easiest way to use Studio is with npx, which requires no installation: + +```bash +npx -y @studio-mcp/studio echo "{message}" +``` + +**Pros:** +- No global packages to manage +- Always uses the latest version +- No installation step needed + +**Cons:** +- Slightly slower first run (caches afterward) +- Requires `-y` flag in MCP configs + +**Best for:** Quick testing, MCP client configurations + +### Method 2: Global Installation + +Install Studio globally for faster execution: + +```bash +npm install -g @studio-mcp/studio +``` + +Verify installation: + +```bash +studio --version +``` + +Use directly: + +```bash +studio echo "{message}" +``` + +**Pros:** +- Faster execution (no npx overhead) +- Cleaner command (just `studio`) +- Better for local development + +**Cons:** +- Requires manual updates +- Global package management +- May need sudo on some systems + +**Best for:** Frequent local use, development + +### Method 3: Local Installation + +Install in a project: + +```bash +npm install @studio-mcp/studio +``` + +Use via package.json scripts: + +```json +{ + "scripts": { + "mcp:echo": "studio echo \"{message}\"" + } +} +``` + +**Best for:** Project-specific tools + +### Method 4: From Source + +Clone and build for development: + +```bash +git clone https://github.com/studio-mcp/studio.git +cd studio +npm install +npm run build +``` + +Run with bun (development): + +```bash +bun run dev echo "{message}" +``` + +Or link globally: + +```bash +npm link +studio echo "{message}" +``` + +**Best for:** Contributing to Studio, debugging + +## Platform-Specific Notes + +### macOS + +Standard installation works out of the box: + +```bash +npm install -g @studio-mcp/studio +``` + +Claude Desktop config location: +``` +~/Library/Application Support/Claude/claude_desktop_config.json +``` + +### Windows + +Use an elevated command prompt or PowerShell: + +```bash +npm install -g @studio-mcp/studio +``` + +Claude Desktop config location: +``` +%APPDATA%\Claude\claude_desktop_config.json +``` + +### Linux + +You may need to use sudo for global installation: + +```bash +sudo npm install -g @studio-mcp/studio +``` + +Or use a node version manager (nvm) to avoid sudo: + +```bash +# Install nvm first +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash + +# Install Node via nvm +nvm install 20 +nvm use 20 + +# Now install Studio without sudo +npm install -g @studio-mcp/studio +``` + +## Package Managers + +Studio works with all major Node package managers: + +### npm (default) + +```bash +npm install -g @studio-mcp/studio +``` + +### yarn + +```bash +yarn global add @studio-mcp/studio +``` + +### pnpm + +```bash +pnpm add -g @studio-mcp/studio +``` + +### bun + +```bash +bun install -g @studio-mcp/studio +``` + +## Updating + +### Update npx (automatic) + +npx automatically uses the latest version. To force update the cache: + +```bash +npx clear-npx-cache +npx -y @studio-mcp/studio --version +``` + +### Update global installation + +```bash +npm update -g @studio-mcp/studio +``` + +Check the installed version: + +```bash +studio --version +``` + +### Update local installation + +```bash +npm update @studio-mcp/studio +``` + +## Uninstalling + +### Remove global installation + +```bash +npm uninstall -g @studio-mcp/studio +``` + +### Remove npx cache + +```bash +npm cache clean --force +``` + +### Remove local installation + +```bash +npm uninstall @studio-mcp/studio +``` + +## Troubleshooting + +### Command not found + +If `studio` is not found after global installation: + +1. Check if npm global bin is in your PATH: + ```bash + npm config get prefix + ``` + +2. Add to PATH (add to ~/.bashrc or ~/.zshrc): + ```bash + export PATH="$(npm config get prefix)/bin:$PATH" + ``` + +3. Reload your shell: + ```bash + source ~/.bashrc # or ~/.zshrc + ``` + +### Permission errors on macOS/Linux + +Use nvm instead of sudo: + +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash +nvm install 20 +npm install -g @studio-mcp/studio +``` + +### npx slow first run + +The first `npx` run downloads and caches the package. Subsequent runs are faster. For even faster execution, use global installation instead. + +## Verifying Installation + +Test your installation: + +```bash +# Check version +studio --version + +# Run help +studio --help + +# Test a simple command +studio echo "Hello, Studio!" +``` + +You should see the MCP protocol messages on stdout (this is normal for MCP servers). + +## Next Steps + +- [Getting Started](/guide/getting-started) - Create your first tool +- [Configuration](/guide/config-claude) - Set up with MCP clients +- [Template Syntax](/reference/template-syntax) - Learn the template language diff --git a/docs/guide/what-is-studio.md b/docs/guide/what-is-studio.md new file mode 100644 index 0000000..aec848a --- /dev/null +++ b/docs/guide/what-is-studio.md @@ -0,0 +1,95 @@ +# What is Studio MCP? + +Studio MCP is a lightweight tool that converts any command-line interface (CLI) command into a Model Context Protocol (MCP) tool that can be used by AI assistants like Claude, Cursor, and other MCP-compatible clients. + +## The Problem + +Building MCP servers traditionally requires: + +- Writing TypeScript or JavaScript code +- Setting up build systems and dependencies +- Creating JSON schemas manually +- Handling parameter validation +- Managing process execution +- Publishing and maintaining packages + +This complexity creates a high barrier for adding simple CLI tools to AI assistants. + +## The Solution + +Studio MCP eliminates all this complexity. Instead of writing code, you simply: + +1. **Choose a CLI command** - Any shell command you want to expose +2. **Add template syntax** - Use simple `{argument}` syntax for parameters +3. **Configure your client** - Add one JSON entry to your MCP config + +Studio automatically: +- Parses your template +- Generates the JSON schema +- Validates parameters +- Executes the command +- Returns the output + +## Example + +Instead of writing a full MCP server to expose the `echo` command, you just write: + +```bash +studio echo "{message}" +``` + +Studio converts this into an MCP tool with: +- Tool name: `echo` +- Parameter: `message` (string, required) +- Execution: Runs `echo` with the provided message + +## Use Cases + +Studio MCP is perfect for: + +- **Quick prototyping** - Test MCP integration ideas without building servers +- **System utilities** - Expose `curl`, `git`, `grep`, and other CLI tools +- **Custom scripts** - Make your shell scripts AI-accessible +- **Text-to-speech** - Let AI assistants speak (`say` command) +- **API calls** - Wrap HTTP requests with templated URLs +- **File operations** - Safe, parameterized file manipulation + +## How It Works + +``` +┌─────────────────┐ +│ MCP Client │ (Claude, Cursor, etc.) +│ (AI Assistant) │ +└────────┬────────┘ + │ MCP Protocol + │ +┌────────▼────────┐ +│ Studio MCP │ +│ - Parse template +│ - Generate schema +│ - Validate args +│ - Execute command +└────────┬────────┘ + │ spawn() + │ +┌────────▼────────┐ +│ CLI Command │ (echo, curl, git, etc.) +└─────────────────┘ +``` + +## What Studio Is Not + +Studio MCP is intentionally simple and focused. It is **not**: + +- A replacement for complex MCP servers with custom logic +- A security sandbox (it runs commands with your permissions) +- A package manager or dependency resolver +- A programming language or scripting environment + +For complex use cases requiring custom logic, state management, or advanced features, you should build a traditional MCP server. Studio is for when you just want to expose a CLI command quickly and easily. + +## Next Steps + +- [Getting Started](/guide/getting-started) - Install and run your first command +- [Template Syntax](/reference/template-syntax) - Learn the template language +- [Examples](/examples/basic) - See common usage patterns diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a51b368 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,86 @@ +--- +layout: home + +hero: + name: Studio MCP + text: Turn any CLI into an MCP tool + tagline: The simplest way to add command-line tools to AI assistants + actions: + - theme: brand + text: Get Started + link: /guide/getting-started + - theme: alt + text: View on GitHub + link: https://github.com/studio-mcp/studio + +features: + - icon: 🚀 + title: Simple & Lightweight + details: Convert any CLI command into an MCP tool with a single command. No complex setup or configuration required. + + - icon: 🎯 + title: Template-Based + details: Use intuitive Mustache-like syntax to define command arguments. Studio automatically generates the schema. + + - icon: 🔌 + title: Universal Compatibility + details: Works with Claude Desktop, Cursor, VSCode, and any MCP-compatible client. + + - icon: ⚡ + title: Zero Dependencies + details: Use npx to run studio without installation. No global dependencies or package management hassles. + + - icon: 🎨 + title: Flexible Arguments + details: Support for required/optional parameters, arrays, boolean flags, and complex templates. + + - icon: 🔍 + title: Built-in Debugging + details: Debug mode with stderr or file logging helps troubleshoot tool execution. +--- + +## Quick Start + +Install globally: + +```bash +npm install -g @studio-mcp/studio +``` + +Or use with npx (no installation): + +```bash +npx -y @studio-mcp/studio echo "{message}" +``` + +## Example Usage + +Add a simple echo tool to Claude Desktop: + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": ["-y", "@studio-mcp/studio", "echo", "{text}"] + } + } +} +``` + +Now Claude can use the echo tool with any text input! + +## Why Studio MCP? + +Traditional MCP servers require: +- Writing TypeScript/JavaScript code +- Setting up build tools +- Managing dependencies +- Publishing to npm + +With Studio MCP, you just: +1. Choose a CLI command +2. Add template syntax for arguments +3. Add to your MCP client config + +That's it! Studio handles schema generation, validation, and execution automatically. diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..91445a5 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,14 @@ +{ + "name": "studio-mcp-docs", + "version": "1.0.0", + "description": "Documentation for Studio MCP", + "type": "module", + "scripts": { + "dev": "vitepress dev", + "build": "vitepress build", + "preview": "vitepress preview" + }, + "devDependencies": { + "vitepress": "^1.0.0" + } +} diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md new file mode 100644 index 0000000..4b36ed4 --- /dev/null +++ b/docs/reference/architecture.md @@ -0,0 +1,680 @@ +# Architecture + +This document explains how Studio MCP works internally, from template parsing to command execution. + +## Overview + +Studio MCP is a lightweight bridge between the Model Context Protocol and command-line tools. It consists of several key components working together: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MCP Client │ +│ (Claude, Cursor, etc.) │ +└────────────────────────┬────────────────────────────────────┘ + │ JSON-RPC over stdio + │ +┌────────────────────────▼────────────────────────────────────┐ +│ Studio MCP │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 1. Parse Arguments │ │ +│ │ - Extract flags (--debug, --log) │ │ +│ │ - Extract command template │ │ +│ └──────────────────────┬───────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼───────────────────────────────┐ │ +│ │ 2. Template Parsing │ │ +│ │ - Tokenize shell words │ │ +│ │ - Identify fields: {name}, [name], etc. │ │ +│ │ - Extract descriptions │ │ +│ └──────────────────────┬───────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼───────────────────────────────┐ │ +│ │ 3. Schema Generation │ │ +│ │ - Convert fields to JSON schema │ │ +│ │ - Define types (string, array, boolean) │ │ +│ │ - Mark required vs optional │ │ +│ └──────────────────────┬───────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼───────────────────────────────┐ │ +│ │ 4. MCP Server Registration │ │ +│ │ - Create tool with schema │ │ +│ │ - Set up JSON-RPC handlers │ │ +│ │ - Start stdio transport │ │ +│ └──────────────────────┬───────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼───────────────────────────────┐ │ +│ │ 5. Request Handling │ │ +│ │ - Receive tool call from client │ │ +│ │ - Validate parameters with Zod │ │ +│ │ - Render command with values │ │ +│ └──────────────────────┬───────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼───────────────────────────────┐ │ +│ │ 6. Command Execution │ │ +│ │ - Spawn shell command │ │ +│ │ - Capture stdout/stderr │ │ +│ │ - Return output to client │ │ +│ └──────────────────────────────────────────────────────┘ │ +└────────────────────────┬────────────────────────────────────┘ + │ spawn() + │ +┌────────────────────────▼────────────────────────────────────┐ +│ Shell Command │ +│ (echo, curl, git, etc.) │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Component Details + +### 1. Argument Parsing + +**Location:** `src/index.ts:parseArgs()` + +Parses command-line arguments into Studio options and command template. + +**Input:** +```javascript +process.argv = [ + 'node', 'studio.js', + '--debug', + '--log', '/tmp/studio.log', + 'echo', '{message}' +] +``` + +**Output:** +```javascript +{ + debug: true, + logFile: '/tmp/studio.log', + commandArgs: ['echo', '{message}'] +} +``` + +**Algorithm:** +1. Skip first two args (node, script) +2. Parse flags until non-flag found or `--` encountered +3. Remaining args become command template + +### 2. Template Parsing + +**Location:** `src/studio/parse.ts` + +Converts command template into structured tokens. + +#### Tokenization + +**Function:** `fromArgs(args: string[]): Template` + +**Input:** +```javascript +['echo', '{message}', 'world'] +``` + +**Process:** +1. Iterate through each argument +2. Check for template patterns: + - `{name}` → FieldToken (required) + - `[name]` → FieldToken (optional) + - `[--flag]` → FieldToken (boolean) + - Otherwise → TextToken +3. Parse descriptions after `#` +4. Handle arrays with `...` suffix + +**Output:** +```javascript +{ + args: [ + { kind: 'text', value: 'echo' }, + { kind: 'field', name: 'message', required: true }, + { kind: 'text', value: 'world' } + ], + fields: [ + { kind: 'field', name: 'message', required: true } + ] +} +``` + +#### Field Patterns + +Parsed using these regex patterns: + +```typescript +// Required: {name} or {{name}} +/^\{\{?(\w+)(?:\s*#\s*(.+?))?\}?\}$/ + +// Optional: [name] +/^\[(\w+)(?:\s*#\s*(.+?))?\]$/ + +// Array: {name...} or [name...] +/^\{(\w+)\.\.\.(?:\s*#\s*(.+?))?\}$/ +/^\[(\w+)\.\.\.(?:\s*#\s*(.+?))?\]$/ + +// Boolean: [--flag] +/^\[(--?\w+)(?:\s*#\s*(.+?))?\]$/ +``` + +### 3. Schema Generation + +**Location:** `src/studio/schema.ts:generateInputSchema()` + +Converts template fields into JSON Schema for MCP. + +**Input:** +```javascript +fields: [ + { name: 'message', required: true, array: false, boolean: false }, + { name: 'count', required: false, array: false, boolean: false } +] +``` + +**Output:** +```javascript +{ + type: 'object', + properties: { + message: { type: 'string', description: null }, + count: { type: 'string', description: null } + }, + required: ['message'] +} +``` + +**Field Type Mapping:** + +| Template | JSON Schema Type | +|----------|------------------| +| `{name}` | `{ type: 'string' }` | +| `[name]` | `{ type: 'string' }` | +| `{name...}` | `{ type: 'array', items: { type: 'string' } }` | +| `[--flag]` | `{ type: 'boolean' }` | + +### 4. Zod Schema Conversion + +**Location:** `src/index.ts:schemaToZod()` + +Converts JSON Schema to Zod schema for runtime validation. + +**Input:** +```javascript +{ + type: 'object', + properties: { + message: { type: 'string' } + }, + required: ['message'] +} +``` + +**Output:** +```javascript +z.object({ + message: z.string() +}) +``` + +**Type Conversion:** + +```typescript +// String +{ type: 'string' } → z.string() + +// Array +{ type: 'array', items: { type: 'string' } } → z.array(z.string()) + +// Boolean +{ type: 'boolean' } → z.boolean() + +// Optional (not in required) +Not in required → .optional() +``` + +### 5. MCP Server Setup + +**Location:** `src/index.ts:main()` + +Creates and configures the MCP server. + +**Steps:** + +1. **Create server instance:** + ```typescript + const server = new McpServer({ + name: 'studio-mcp', + version: '0.0.0' + }) + ``` + +2. **Derive tool name from command:** + ```typescript + const toolName = commandName.replace(/-/g, '_') + // 'git-status' → 'git_status' + ``` + +3. **Register tool:** + ```typescript + server.tool( + toolName, + inputSchema, + async (params) => { + // Handle tool call + } + ) + ``` + +4. **Start transport:** + ```typescript + const transport = new StdioServerTransport() + await server.connect(transport) + ``` + +### 6. Command Rendering + +**Location:** `src/studio/render.ts:buildCommandArgs()` + +Renders the final command with parameter values. + +**Input:** +```javascript +template: { + args: [ + { kind: 'text', value: 'echo' }, + { kind: 'field', name: 'message' }, + { kind: 'text', value: 'world' } + ] +}, +params: { message: 'Hello' } +``` + +**Process:** + +1. Iterate through template tokens +2. For TextToken: add value as-is +3. For FieldToken: + - String: add parameter value + - Array: spread values + - Boolean: add flag if true + +**Output:** +```javascript +['echo', 'Hello', 'world'] +``` + +#### Array Rendering + +```javascript +// Template +template: [ + { kind: 'text', value: 'git' }, + { kind: 'field', name: 'args', array: true } +] + +// Parameters +params: { args: ['status', '--short'] } + +// Output +['git', 'status', '--short'] +``` + +#### Boolean Rendering + +```javascript +// Template +template: [ + { kind: 'text', value: 'ls' }, + { kind: 'field', name: 'all', boolean: true, value: '--all' } +] + +// Parameters (all: true) +params: { all: true } +// Output: ['ls', '--all'] + +// Parameters (all: false) +params: { all: false } +// Output: ['ls'] +``` + +### 7. Command Execution + +**Location:** `src/index.ts` (tool handler) + +Executes the rendered command and returns output. + +**Process:** + +```typescript +const { spawn } = require('child_process') + +const [cmd, ...args] = renderedCommand +const child = spawn(cmd, args, { + stdio: ['ignore', 'pipe', 'pipe'] +}) + +let stdout = '' +let stderr = '' + +child.stdout.on('data', (data) => { + stdout += data.toString() +}) + +child.stderr.on('data', (data) => { + stderr += data.toString() +}) + +child.on('close', (code) => { + if (code === 0) { + return { content: [{ type: 'text', text: stdout }] } + } else { + return { isError: true, content: stderr } + } +}) +``` + +## Data Flow Example + +Complete flow for `studio echo "{message}"`: + +### Step 1: Parse Arguments + +``` +Input: ['studio', 'echo', '{message}'] +Output: commandArgs = ['echo', '{message}'] +``` + +### Step 2: Parse Template + +``` +Input: ['echo', '{message}'] +Output: { + args: [ + { kind: 'text', value: 'echo' }, + { kind: 'field', name: 'message', required: true } + ], + fields: [ + { name: 'message', required: true } + ] +} +``` + +### Step 3: Generate Schema + +``` +Input: fields = [{ name: 'message', required: true }] +Output: { + type: 'object', + properties: { + message: { type: 'string' } + }, + required: ['message'] +} +``` + +### Step 4: Register Tool + +``` +Tool name: 'echo' +Tool schema: { ... } +Tool handler: async (params) => { ... } +``` + +### Step 5: Receive Call + +``` +MCP client sends: +{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "echo", + "arguments": { "message": "Hello" } + } +} +``` + +### Step 6: Render Command + +``` +Input: template + { message: 'Hello' } +Output: ['echo', 'Hello'] +``` + +### Step 7: Execute + +``` +spawn('echo', ['Hello']) +stdout: "Hello\n" +Exit code: 0 +``` + +### Step 8: Return Result + +``` +MCP server responds: +{ + "jsonrpc": "2.0", + "result": { + "content": [ + { "type": "text", "text": "Hello\n" } + ] + } +} +``` + +## Key Design Decisions + +### 1. Stdio Transport + +Studio uses stdio for MCP communication because: +- Simplest integration with MCP clients +- No network configuration needed +- Process isolation and security +- Standard for CLI tools + +### 2. Shell Word Parsing + +Arguments are parsed as shell words: +- Supports quoted strings: `"hello world"` +- Handles escape sequences +- Preserves spaces in quotes +- Compatible with shell syntax + +### 3. Template Syntax + +Design choices: +- **Familiar:** Mustache-like syntax developers know +- **Minimal:** Only braces and brackets, no complex DSL +- **Shell-compatible:** Works in JSON strings +- **Descriptive:** Inline descriptions with `#` + +### 4. Schema Generation + +Automatic schema generation provides: +- No manual JSON schema writing +- Guaranteed schema/template sync +- Type safety with Zod validation +- Clear parameter documentation + +### 5. Single Tool Per Server + +Each Studio instance serves one tool because: +- Simple mental model +- Easy configuration +- Independent tool lifecycles +- No cross-tool complexity + +## Performance Characteristics + +### Startup Time + +``` +Component Time +───────────────────── ───── +Node.js startup ~50ms +Parse arguments <1ms +Parse template <1ms +Generate schema <1ms +Start MCP server ~10ms +───────────────────── ───── +Total ~60ms +``` + +### Runtime Overhead + +Per tool call: +``` +Component Time +───────────────────── ───── +Validate params <1ms +Render command <1ms +Spawn process ~5ms +Execute command varies +Parse output <1ms +───────────────────── ───── +Studio overhead ~7ms +``` + +The command execution time dominates; Studio adds minimal overhead. + +## Dependencies + +### Core Dependencies + +- **@modelcontextprotocol/sdk** - MCP protocol implementation +- **zod** - Schema validation + +### Why So Few? + +Minimal dependencies provide: +- Fast installation +- Small bundle size +- Fewer security vulnerabilities +- Easy auditing +- Stable foundation + +## Error Handling + +### Template Parsing Errors + +```typescript +// Invalid template +"{}" → Error: Empty field name +"{a{b}}" → Error: Nested templates not supported +``` + +### Validation Errors + +```typescript +// Missing required parameter +Required: message +Provided: {} +Error: "message is required" +``` + +### Execution Errors + +```typescript +// Command not found +Command: nonexistent +Error: spawn ENOENT + +// Command failed +Exit code: 1 +Stderr: "error message" +``` + +## Security Considerations + +### Command Injection Prevention + +Studio does NOT prevent command injection. It's designed to: +- Run the specified command with parameters +- Not interpret or execute shell syntax in parameters + +MCP clients should sanitize user input before calling tools. + +### Process Isolation + +Each command runs as a subprocess: +- Inherits parent environment +- No shell interpretation (uses spawn, not exec) +- Isolated from MCP server process + +### Permission Model + +Studio runs with the permissions of the user who started it: +- No privilege escalation +- Standard file system permissions apply +- Commands run as the invoking user + +## Testing Architecture + +### Unit Tests + +Test individual components: +- Template parsing +- Schema generation +- Command rendering + +**Location:** `src/__tests__/*.test.ts` + +### Integration Tests + +Test complete flows: +- MCP protocol handling +- Command execution +- Error scenarios + +### Test Utilities + +```typescript +// Parse test +import { fromArgs } from '../studio/parse' +const template = fromArgs(['echo', '{message}']) + +// Schema test +import { generateInputSchema } from '../studio/schema' +const schema = generateInputSchema(template.fields) + +// Render test +import { buildCommandArgs } from '../studio/render' +const command = buildCommandArgs(template, { message: 'test' }) +``` + +## Extensibility Points + +While Studio is intentionally minimal, these extension points exist: + +### Custom Transports + +Replace StdioServerTransport: +```typescript +import { SSEServerTransport } from '@modelcontextprotocol/sdk' +const transport = new SSEServerTransport(...) +``` + +### Custom Validation + +Extend schema generation: +```typescript +// Add custom constraints +const schema = generateInputSchema(fields) +schema.properties.email.format = 'email' +``` + +### Middleware + +Wrap tool handler: +```typescript +server.tool(toolName, schema, async (params) => { + // Pre-processing + const result = await originalHandler(params) + // Post-processing + return result +}) +``` + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Syntax details +- [Development](/guide/development) - Contributing guide +- [Examples](/examples/advanced) - Advanced patterns diff --git a/docs/reference/cli-options.md b/docs/reference/cli-options.md new file mode 100644 index 0000000..cf2a6ea --- /dev/null +++ b/docs/reference/cli-options.md @@ -0,0 +1,471 @@ +# Command Line Options + +Studio MCP can be run directly from the command line with various options. This reference covers all available flags and arguments. + +## Basic Usage + +```bash +studio [options] [template-args...] +``` + +## Synopsis + +```bash +studio [--help] [--version] [--debug] [--log ] [--] [args...] +``` + +## Options + +### `--help`, `-h` + +Display help information and exit. + +```bash +studio --help +studio -h +``` + +**Output:** +``` +Studio MCP - Turn any CLI command into an MCP tool + +Usage: studio [options] [template-args...] + +Options: + -h, --help Show this help message + --version Show version information + --debug Print debug logs to stderr + --log Write debug logs to file + -- Stop parsing flags + +Examples: + studio echo "{message}" + studio --debug git status + studio --log /tmp/studio.log curl "{url}" +``` + +### `--version` + +Display version information and exit. + +```bash +studio --version +``` + +**Output:** +``` +0.0.0 +``` + +### `--debug` + +Enable debug logging to stderr. + +```bash +studio --debug echo "{message}" +``` + +**Debug output includes:** +- Template parsing details +- Generated JSON schema +- Parameter validation +- Command execution details +- Exit codes and errors + +**Example output:** +``` +[DEBUG] Parsing template: echo "{message}" +[DEBUG] Generated schema: {"type":"object","properties":...} +[DEBUG] Executing command: ["echo", "Hello"] +[DEBUG] Exit code: 0 +``` + +**Note:** Debug output goes to stderr, MCP protocol goes to stdout. + +### `--log ` + +Write debug logs to a specified file instead of stderr. + +```bash +studio --log /tmp/studio.log echo "{message}" +``` + +**Log file format:** +Same as `--debug`, but written to file: +``` +2025-01-15T12:34:56.789Z [DEBUG] Parsing template... +2025-01-15T12:34:56.790Z [DEBUG] Generated schema... +``` + +**Use cases:** +- Debugging MCP client integrations +- Persistent logging +- Log analysis +- Troubleshooting production issues + +### `--` + +Stop parsing flags and treat remaining arguments as command. + +```bash +studio -- command --with-its-own-flags "{arg}" +``` + +**Useful when:** +- Command has flags that conflict with Studio's flags +- Command starts with `--` +- You want to be explicit about where Studio options end + +**Example:** +```bash +# Without --, Studio tries to parse --verbose +studio echo --verbose "{message}" # Error + +# With --, --verbose is passed to echo +studio -- echo --verbose "{message}" # Works +``` + +## Combining Options + +Options can be combined: + +```bash +# Debug to both stderr and file +studio --debug --log /tmp/studio.log echo "{message}" + +# Multiple options before command +studio --debug --log /tmp/test.log -- git "{args...}" +``` + +## Command Arguments + +Everything after options is the command template: + +```bash +studio [options] [template-args...] +``` + +### Command + +The actual command to execute: + +```bash +studio echo "{message}" +# ^^^^ command +``` + +Can be: +- System commands: `echo`, `curl`, `git` +- Scripts: `/path/to/script.sh` +- Executables: `/usr/bin/python3` + +### Template Arguments + +Arguments with template syntax: + +```bash +studio curl "https://api.example.com/{endpoint}" +# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ template arg +``` + +See [Template Syntax](/reference/template-syntax) for details. + +## Examples + +### Basic Echo + +```bash +studio echo "{message}" +``` + +### Debug Mode + +```bash +studio --debug curl "https://api.github.com/{endpoint}" +``` + +### Log to File + +```bash +studio --log /tmp/studio.log git status +``` + +### Complex Command with Flags + +```bash +studio -- git -C "{repo_path}" log --oneline "{branch}" +``` + +### Multiple Templates + +```bash +studio curl -X "{method}" "https://api.example.com/{endpoint}" +``` + +## MCP Client Usage + +In MCP client configurations, options go in the `args` array: + +### Claude Desktop + +```json +{ + "mcpServers": { + "echo": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "--log", + "/tmp/studio-echo.log", + "echo", + "{message}" + ] + } + } +} +``` + +### Cursor + +```json +{ + "mcpServers": { + "git": { + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--log", + "/tmp/cursor-git.log", + "git", + "[args...]" + ] + } + } +} +``` + +### VSCode + +```json +{ + "mcp.servers": { + "curl": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@studio-mcp/studio", + "--debug", + "curl", + "{url}" + ] + } + } +} +``` + +## Environment Variables + +Studio doesn't use environment variables for configuration, but respects: + +### `PATH` + +Used to find commands: + +```bash +# These use PATH +studio echo "{message}" +studio git "{args...}" +studio curl "{url}" +``` + +### `HOME` + +Used for `~` expansion in file paths: + +```bash +studio --log ~/studio.log echo "{message}" +``` + +## Exit Codes + +Studio returns exit codes to indicate success or failure: + +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | General error | +| 2 | Invalid arguments | +| 126 | Command not executable | +| 127 | Command not found | +| 130 | Terminated by Ctrl+C | + +**Examples:** + +```bash +# Success +studio echo "Hello" +echo $? # 0 + +# Command not found +studio nonexistent-command +echo $? # 127 + +# Invalid template +studio echo "{" +echo $? # 2 +``` + +## Standard Streams + +### stdin + +MCP protocol input (JSON-RPC messages). + +```bash +# MCP client sends requests to stdin +echo '{"jsonrpc":"2.0","method":"tools/list"}' | studio echo "{message}" +``` + +### stdout + +MCP protocol output (JSON-RPC responses). + +```bash +# Studio sends responses to stdout +studio echo "{message}" > mcp-output.json +``` + +### stderr + +Debug logs and errors. + +```bash +# Debug output goes to stderr +studio --debug echo "{message}" 2> debug.log +``` + +## Debugging Options + +### Full Debug Output + +```bash +studio --debug echo "{message}" 2>&1 | tee full-output.log +``` + +This captures: +- Debug logs (stderr) +- MCP protocol (stdout) + +### Separate Streams + +```bash +studio --debug echo "{message}" \ + 1> mcp-protocol.log \ + 2> debug.log +``` + +This separates: +- MCP protocol → `mcp-protocol.log` +- Debug output → `debug.log` + +### Both Debug and Log File + +```bash +studio --debug --log /tmp/studio.log echo "{message}" +``` + +This outputs debug to: +- stderr (terminal) +- `/tmp/studio.log` (file) + +## Shell Integration + +### Bash/Zsh + +Add to `.bashrc` or `.zshrc`: + +```bash +# Alias for common commands +alias studio-debug='studio --debug --log /tmp/studio.log' + +# Function wrapper +studio-test() { + studio --debug "$@" 2>&1 | less +} +``` + +### Fish + +Add to `~/.config/fish/config.fish`: + +```fish +# Alias +alias studio-debug='studio --debug --log /tmp/studio.log' + +# Function +function studio-test + studio --debug $argv 2>&1 | less +end +``` + +## Testing Commands + +### Test Template Parsing + +```bash +# See generated schema +studio --debug echo "{message}" 2>&1 | grep "Generated schema" +``` + +### Test Command Execution + +```bash +# See what command runs +studio --debug curl "{url}" 2>&1 | grep "Executing" +``` + +### Test with MCP Inspector + +```bash +mcp-inspector studio --debug --log /tmp/inspector.log echo "{message}" +``` + +## Common Patterns + +### Development Testing + +```bash +studio --debug --log ./studio-dev.log echo "{message}" +``` + +### Production Use + +```bash +# No debug output +studio curl "https://api.example.com/{endpoint}" +``` + +### Troubleshooting + +```bash +studio --debug --log /tmp/troubleshoot.log -- problematic-command "{arg}" +``` + +### Quick Prototyping + +```bash +# Test different templates quickly +studio echo "{a} {b} {c}" +studio echo "[a] [b] [c]" +studio echo "[args...]" +``` + +## Next Steps + +- [Template Syntax](/reference/template-syntax) - Learn template features +- [Debugging](/guide/debugging) - Troubleshooting guide +- [Examples](/examples/basic) - Real-world usage diff --git a/docs/reference/template-syntax.md b/docs/reference/template-syntax.md new file mode 100644 index 0000000..7fd6e92 --- /dev/null +++ b/docs/reference/template-syntax.md @@ -0,0 +1,498 @@ +# Template Syntax + +Studio MCP uses a simple Mustache-like template syntax to define command arguments. This reference covers all syntax features and rules. + +## Basic Syntax + +Templates use curly braces `{}` and square brackets `[]` to define parameters: + +| Syntax | Type | Required | Example | +|--------|------|----------|---------| +| `{name}` | String | Yes | `{message}` | +| `{{name}}` | String | Yes | `{{message}}` (legacy) | +| `[name]` | String | No | `[optional]` | +| `{name...}` | Array | Yes (1+) | `{files...}` | +| `[name...]` | Array | No | `[args...]` | +| `[--flag]` | Boolean | No | `[--verbose]` | + +## Required Arguments + +Use curly braces to define required parameters. + +### Single Brace (Recommended) + +```bash +studio echo "{message}" +``` + +Creates a required `message` parameter (string). + +### Double Brace (Legacy) + +```bash +studio echo "{{message}}" +``` + +Also creates a required parameter. Both syntaxes are equivalent. + +### Example + +```bash +# Command +studio curl "https://api.github.com/{endpoint}" + +# Schema +{ + "endpoint": { + "type": "string", + "required": true + } +} + +# Usage +endpoint: "users/octocat" +# Executes: curl https://api.github.com/users/octocat +``` + +## Optional Arguments + +Use square brackets for optional parameters. + +```bash +studio echo "Hello" "[name]" +``` + +Creates an optional `name` parameter. + +### Example + +```bash +# Command +studio git status "[--short]" + +# When provided +git status --short + +# When omitted +git status +``` + +## Array Arguments + +Arrays allow multiple values for a single parameter. + +### Required Array + +```bash +studio tar -czf archive.tar.gz "{files...}" +``` + +Requires at least one file. + +```bash +# Usage +files: ["file1.txt", "file2.txt", "file3.txt"] +# Executes: tar -czf archive.tar.gz file1.txt file2.txt file3.txt +``` + +### Optional Array + +```bash +studio git log "[paths...]" +``` + +Accepts zero or more paths. + +```bash +# With values +paths: ["src/", "tests/"] +# Executes: git log src/ tests/ + +# Without values +paths: [] +# Executes: git log +``` + +## Boolean Flags + +Boolean flags appear or disappear based on a boolean value. + +```bash +studio ls "[--all]" "[--long]" +``` + +Creates two boolean parameters: `all` and `long`. + +```bash +# Usage +all: true, long: false +# Executes: ls --all + +# Usage +all: true, long: true +# Executes: ls --all --long + +# Usage +all: false, long: false +# Executes: ls +``` + +### Flag Naming + +The flag name is derived from the template: + +- `[--verbose]` → parameter: `verbose` +- `[--all]` → parameter: `all` +- `[-a]` → parameter: `a` + +Parameter names automatically: +- Remove dashes +- Convert to lowercase +- Allow underscores + +So `[--dry-run]` becomes parameter `dry_run` or `dryrun`. + +## Descriptions + +Add descriptions after `#` to document parameters. + +```bash +studio echo "{message # The text to echo}" +``` + +Creates a parameter with description "The text to echo". + +### Description Syntax + +```bash +# Basic description +"{message # A message to display}" + +# Optional with description +"[name # Optional user name]" + +# Array with description +"{files... # List of files to process}" + +# Boolean with description +"[--verbose # Enable verbose output]" +``` + +### Cursor Compatibility + +Cursor has a bug with spaces in descriptions. Use underscores: + +```bash +# Claude Desktop (works) +"{message # A message to display}" + +# Cursor (required) +"{message#message_to_display}" +``` + +## Multiple Templates in One Argument + +You can use multiple templates in a single argument: + +```bash +studio echo "{{greeting}} {{name}}!" +``` + +```bash +# Usage +greeting: "Hello", name: "World" +# Executes: echo "Hello World!" +``` + +### Complex Example + +```bash +studio curl "https://api.example.com/{{version}}/{{endpoint}}?key={{api_key}}" +``` + +```bash +# Usage +version: "v1", endpoint: "users", api_key: "secret123" +# Executes: curl "https://api.example.com/v1/users?key=secret123" +``` + +## Template in URLs + +Templates work well in URLs: + +```bash +studio curl "https://wttr.in/{city}?format={format}" +``` + +```bash +# Usage +city: "London", format: "3" +# Executes: curl "https://wttr.in/London?format=3" +``` + +## Mixing Static and Dynamic Content + +Combine literal text with templates: + +```bash +studio git commit -m "{message # Commit message}" +``` + +```bash +# Usage +message: "Fix bug in parser" +# Executes: git commit -m "Fix bug in parser" +``` + +## Field Naming Rules + +Parameter names must follow these rules: + +- **Allowed characters**: Letters, numbers, underscores, dashes +- **Case-insensitive**: `{userName}` and `{username}` are the same +- **Dash/underscore equivalence**: `{user-name}` and `{user_name}` are the same +- **No spaces**: `{user name}` is invalid + +### Valid Names + +```bash +{message} ✓ +{user_name} ✓ +{user-name} ✓ +{fileName} ✓ +{file123} ✓ +{_private} ✓ +``` + +### Invalid Names + +```bash +{user name} ✗ (space) +{user@name} ✗ (special char) +{123file} ✗ (starts with number) +{} ✗ (empty) +``` + +## Edge Cases + +### Empty Arguments + +```bash +# Valid: empty text arguments +studio echo "" "{message}" "" + +# Invalid: empty field names +studio echo "{}" # Error +``` + +### Nested Templates + +Not supported: + +```bash +# Invalid +studio echo "{{name{suffix}}}" # Error +``` + +### Escaped Braces + +To include literal braces, don't use templates: + +```bash +# Literal braces +studio echo "{ not a template }" + +# This works because spaces around braces mean it's not a template +``` + +## Complete Examples + +### Example 1: File Operations + +```bash +studio cat "{file_path # Path to file to read}" +``` + +### Example 2: Multiple Required Args + +```bash +studio cp "{source # Source file}" "{dest # Destination file}" +``` + +### Example 3: Optional Flags + +```bash +studio ls "[--all]" "[--long]" "[--human-readable]" "{path}" +``` + +### Example 4: Array with Options + +```bash +studio grep "{pattern}" "[--ignore-case]" "{files... # Files to search}" +``` + +### Example 5: Complex Command + +```bash +studio ffmpeg -i "{input # Input video}" \ + "[--verbose]" \ + -c:v "{codec # Video codec}" \ + "{output # Output file}" +``` + +### Example 6: API Request + +```bash +studio curl -X "{method # HTTP method}" \ + -H "Content-Type: application/json" \ + "[--data {payload}]" \ + "https://api.example.com/{endpoint}" +``` + +## Schema Generation + +Templates automatically generate JSON schemas: + +```bash +# Template +studio echo "{message}" "[name]" + +# Generated Schema +{ + "type": "object", + "properties": { + "message": { + "type": "string", + "description": null + }, + "name": { + "type": "string", + "description": null + } + }, + "required": ["message"] +} +``` + +### Array Schema + +```bash +# Template +studio tar -czf archive.tar.gz "{files...}" + +# Generated Schema +{ + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["files"] +} +``` + +### Boolean Schema + +```bash +# Template +studio ls "[--all]" + +# Generated Schema +{ + "type": "object", + "properties": { + "all": { + "type": "boolean" + } + }, + "required": [] +} +``` + +## Best Practices + +### 1. Use Descriptive Names + +```bash +# Good +"{user_id # The user's ID}" + +# Bad +"{id}" +``` + +### 2. Add Descriptions + +```bash +# Good +"{endpoint # API endpoint path}" + +# Bad +"{endpoint}" +``` + +### 3. Use Optional for Flags + +```bash +# Good +"[--verbose]" + +# Bad (don't make flags required) +"{--verbose}" +``` + +### 4. Array for Variable Arguments + +```bash +# Good +"[files... # Files to process]" + +# Bad (can't handle multiple files) +"[file1] [file2] [file3]" +``` + +### 5. Group Related Args + +```bash +# Good +studio command "{required_arg}" "[optional_arg]" "[--flag]" + +# Bad (hard to understand) +studio command "[--flag]" "{required_arg}" "[optional_arg]" +``` + +## Syntax Quick Reference + +```bash +# Required string +{name} +{{name}} + +# Optional string +[name] + +# Required array (1+ items) +{name...} + +# Optional array (0+ items) +[name...] + +# Boolean flag +[--flag] + +# With description +{name # description} + +# Multiple in one arg +"{{greeting}} {{name}}" +``` + +## Next Steps + +- [Examples](/examples/basic) - See templates in action +- [CLI Options](/reference/cli-options) - Command-line flags +- [Architecture](/reference/architecture) - How parsing works