Skip to content

ukkz/claude-ts-mcps

BranchesTags

Repository files navigation

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をいい感じにしてサブスクだけで無双する

🚀 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 v18 or higher
  • Bun runtime
  • Claude Desktop application
  • API keys for external services (Brave Search, Perplexity/Sonar)

🛠️ Installation

# 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:

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

# 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:

# 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:

# 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:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Other Editors: Check your editor's documentation for Prettier integration.

📚 Resources

📄 License

MIT License

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

19 stars

Watchers

1 watching

Forks

8 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages