--- slug: "claude" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/ukkz/claude-ts-mcps@main/README.md" repo: "https://github.com/ukkz/claude-ts-mcps" source_file: "README.md" branch: "main" --- # Claude TypeScript MCP Servers (For Software Developers) A comprehensive collection of Model Context Protocol (MCP) servers that transform Claude Desktop into a powerful development assistant. This project leverages your flat-rate Claude Pro/Max subscription to provide capabilities similar to Cline, but without the per-token API costs. 日本語による解説記事: [Cline任せでコード書いてたらAPIクレジットが爆散したのでClaude Desktop + MCPをいい感じにしてサブスクだけで無双する](https://zenn.dev/ukkz/articles/c8726063edd2cd) ## 🚀 Features - **File System Operations** - Read, write, and manage files with security restrictions - **Git Integration** - Full Git workflow support including commits, branches, and diffs - **GitHub API** - Manage repositories, issues, PRs, and more with multi-account support - **Web Search** - AI-powered search with Sonar and traditional keyword search with Brave - **Browser Automation** - 30+ Puppeteer tools for web scraping and automation - **Shell Commands** - Execute development commands in a controlled environment - **URL Fetching** - Extract content from web pages with HTML-to-Markdown conversion ## 📋 Requirements - [Node.js](https://nodejs.org/) v18 or higher - [Bun](https://bun.sh/) runtime - [Claude Desktop](https://anthropic.com/claude) application - API keys for external services (Brave Search, Perplexity/Sonar) ## 🛠️ Installation ```bash # Clone the repository git clone https://github.com/yourusername/claude-ts-mcps.git cd claude-ts-mcps # Install dependencies bun install ``` ## ⚙️ Configuration Create a configuration file for Claude Desktop with all the MCP servers: ```json { "mcpServers": { "filesystem": { "command": "/Users/username/.bun/bin/bun", "args": [ "run", "/path/to/claude-ts-mcps/src/filesystem.ts", "/Users/username" ] }, "git": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/git.ts"] }, "github": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/github.ts"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_DEFAULT_TOKEN", "GITHUB_TOKEN_WORK": "YOUR_WORK_ACCOUNT_TOKEN", "GITHUB_TOKEN_PERSONAL": "YOUR_PERSONAL_ACCOUNT_TOKEN" } }, "brave-search": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/brave-search.ts"], "env": { "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY" } }, "sonar": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/sonar.ts"], "env": { "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY" } }, "puppeteer": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/puppeteer/index.ts"] }, "shell": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/shell.ts"] }, "fetch": { "command": "/Users/username/.bun/bin/bun", "args": ["run", "/path/to/claude-ts-mcps/src/fetch.ts"], "env": { "CUSTOM_USER_AGENT": "YOUR_CUSTOM_USER_AGENT", "IGNORE_ROBOTS_TXT": "false" } } } } ``` ## 🔧 Available Tools ### File System Operations (`filesystem`) - **Security**: Restricted to specified directories with symlink protection - **Core Operations**: - Read/write files with encoding support (utf-8, base64, hex) - Partial file reading by byte range or line range - Move, copy, delete, append files - Create directories and manage file trees - **Advanced Editing**: - Text replacement with diff preview - Line-based operations (replace, insert, delete specific lines) - Regular expression replacements with capture groups - **Search Capabilities**: - Search files by name patterns - Search content within files (plain text or regex) - Exclude patterns support - **Batch Operations**: - Execute multiple file operations efficiently - Parallel execution for read operations - Transactional mode with rollback support - **Archive Management**: - Compress files (zip, tar, tar.gz) - Extract archives with overwrite control - **File Monitoring**: - Check for file changes since specific time - Support for change, rename, and delete events - **Use Cases**: Code editing, project management, file analysis, bulk operations ### Git Integration (`git`) - **Full Git Workflow**: init, add, commit, branch, checkout, diff, log - **Repository Management**: status tracking, history viewing - **Tag Management**: - Create lightweight and annotated tags - List tags with pattern filtering - Show tag details and messages - Delete unwanted tags - **Use Cases**: Version control, code review, project history, release management ### GitHub API (`github`) - **Repository Management**: Create, search, manage repositories - **Issues & PRs**: Create, update, merge pull requests and issues - **Release Management**: Create, update, and manage releases - **Multi-Account Support**: Switch between work/personal accounts - **File Operations**: Direct file creation and updates via API ### Web Search Tools #### AI-Powered Search (`sonar`) - **Natural Language Understanding**: Ask complex questions in plain language - **Synthesized Answers**: Get comprehensive responses with citations - **Multiple Models**: - `sonar`: Fast general-purpose search - `sonar-pro`: Complex queries with 200k context - `sonar-reasoning`: Chain-of-thought reasoning - `sonar-deep-research`: Comprehensive research mode - **Use Cases**: Research, fact-checking, learning about complex topics #### Traditional Search (`brave-search`) - **Web Search**: Keyword-based search returning multiple results - **Local Search**: Find businesses and services - **Use Cases**: Quick lookups, finding multiple sources, local information ### Browser Automation (`puppeteer`) Our most comprehensive tool with 30+ functions organized into categories: #### 🧭 Navigation & Basic Interaction - Navigate to URLs, take screenshots - Click elements, fill forms, select options - Hover over elements, execute JavaScript #### ⏳ Wait Operations - Wait for elements, timeouts, navigation - Wait for custom JavaScript conditions #### ⌨️ Keyboard Operations - Press keys and key combinations - Type text with human-like delays #### 📄 Page Management - Set viewport size, go back/forward, reload - Generate PDFs, emulate devices #### 🍪 Cookies & Authentication - Set/get cookies, HTTP authentication #### ℹ️ Information Retrieval - Get page title, URL, HTML content - Extract text and detailed element information #### 🖼️ Frame Operations (Advanced) - List all frames, switch between frames - Execute JavaScript in specific frames - Search elements across all frames #### 🔧 Miscellaneous - Add script tags, clear input fields ### Shell Commands (`shell`) - **Controlled Execution**: Allowlist-based command restrictions - **Development Tools**: npm, yarn, bun, git, node, python, tsc - **Security**: Prevents dangerous operations, directory restrictions - **Features**: Auto-parsing of command strings, output size limits, timeout control - **Streaming Mode**: Now enabled by default! Captures output from long-running processes - Automatically returns partial output after timeout (default: 10s) or buffer limit (100KB) - Normal commands complete as usual; only affects long-running processes - Processes are automatically terminated after streaming timeout (safe default) - Keep processes running with `killOnStreamingTimeout: false` - Perfect for: development servers, build watchers, interactive commands - Disable with `streaming: false` if needed - **Use Cases**: Package management, build processes, script execution, server monitoring ### URL Content Fetching (`fetch`) - **Content Extraction**: Convert HTML to clean Markdown - **Customization**: Custom user agents, robots.txt handling - **Use Cases**: Documentation reading, content analysis ## 💡 Usage Examples ### Development Workflow ``` You: "Create a new React component for user authentication" Claude: *Uses filesystem to create component file, npm to install dependencies* You: "Find examples of OAuth implementation on GitHub" Claude: *Uses GitHub search and fetch to find and analyze implementations* You: "Test the login form on our staging site" Claude: *Uses Puppeteer to navigate, fill forms, and verify functionality* ``` ### Research and Analysis ``` You: "What are the latest best practices for Next.js 14 App Router?" Claude: *Uses Sonar for comprehensive research with citations* You: "Compare our package.json with similar projects" Claude: *Uses GitHub to find similar projects, filesystem to read local files* ``` ### Automation ``` You: "Extract all product prices from this e-commerce site" Claude: *Uses Puppeteer to navigate pages, extract data, and compile results* You: "Monitor our GitHub issues and create a summary" Claude: *Uses GitHub API to fetch issues, analyze patterns, generate report* ``` ## 🔒 Security Considerations - **File System**: Restricted to specified directories only - **Shell**: Commands must be in the allowlist - **Credentials**: Store API keys securely, use environment variables - **GitHub**: Use minimal token permissions - **Fetch**: Respects robots.txt by default ## 🏗️ Project Structure ``` claude-ts-mcps/ ├── src/ │ ├── filesystem.ts # File operations │ ├── git.ts # Git integration │ ├── github.ts # GitHub API (main entry) │ ├── github/ # GitHub implementation │ ├── brave-search.ts # Brave search API │ ├── sonar.ts # Perplexity Sonar API │ ├── sonar/ # Sonar types and utilities │ ├── puppeteer/ # Browser automation │ │ ├── index.ts # Main entry point │ │ ├── tools/ # Tool definitions │ │ ├── handlers/ # Implementation │ │ └── state.ts # State management │ ├── shell.ts # Shell commands (entry) │ ├── shell/ # Shell implementation │ │ ├── index.ts # Main logic │ │ ├── executor.ts # Command execution │ │ ├── types.ts # Type definitions │ │ └── ... # Other modules │ └── fetch.ts # URL fetching └── package.json ``` ## 🚧 Development To add new functionality: 1. Create a new TypeScript file in `src/` 2. Implement the MCP server using `@modelcontextprotocol/sdk` 3. Add tool definitions with clear descriptions 4. Include proper error handling and validation 5. Update the configuration file ### Testing Your Changes ```bash # Run a specific MCP server directly bun run src/your-new-server.ts # Test with Claude Desktop # Update your config and restart Claude ``` ### Type Checking This project uses TypeScript for type safety. Several type checking commands are available: ```bash # Standard type check (all strict checks enabled) bun run type-check # Type check with file watching for development bun run type-check:watch # Type check without unused variable warnings (good for development) bun run check:loose # Strict type check (same as type-check) bun run check:strict ``` #### Current Type Issues The project is functional but has some type issues that are being addressed: - Some Puppeteer APIs need proper type imports - A few cases of potential undefined values need guards - Unused variables in some files (can be ignored during development) These don't affect runtime functionality but will be cleaned up over time. ### Code Formatting This project uses Prettier for consistent code formatting. The following commands are available: ```bash # Format all files bun run format # Check formatting without making changes bun run format:check # Format only source files (src directory) bun run format:src # Check formatting of source files only bun run format:check:src # Run both formatting check and type check bun run lint # Fix formatting and run type check bun run lint:fix ``` #### Prettier Configuration The project uses the following Prettier settings (`.prettierrc`): - **Print Width**: 100 characters (80 for JSON/Markdown) - **Tab Width**: 2 spaces - **Semicolons**: Always - **Quotes**: Double quotes - **Trailing Commas**: All (ES5+) - **Arrow Parens**: Always include parentheses #### Formatting on Save For the best development experience, configure your editor to format on save: **VS Code**: Add to `.vscode/settings.json`: ```json { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode" } ``` **Other Editors**: Check your editor's documentation for Prettier integration. ## 📚 Resources - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [MCP SDK Reference](https://modelcontextprotocol.io/sdks) - [Anthropic Claude](https://www.anthropic.com/claude) - [Brave Search API](https://api.search.brave.com/app/documentation) - [Perplexity API](https://docs.perplexity.ai/) ## 📄 License [MIT License](https://github.com/ukkz/claude-ts-mcps/tree/HEAD/LICENSE)