个人MCP服务器集合

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip (if you already have Python)
pip install uv

brew install fd fzf

sudo apt install fd-find fzf
# Note: On Debian/Ubuntu, fd is installed as 'fdfind'

brew install ripgrep fzf

# For PDF search capabilities (optional)
brew install ripgrep-all pandoc
pip install PyMuPDF  # Or: uv pip install PyMuPDF

sudo apt install ripgrep fzf

# For PDF search capabilities (optional)
# Install ripgrep-all
cargo install ripgrep-all  # Requires Rust/cargo

# Install PyMuPDF
pip install PyMuPDF  # Or: uv pip install PyMuPDF

# Install pandoc
sudo apt install pandoc

git clone https://github.com/yourusername/mcp-personal.git
cd mcp-personal

# Add custom Python servers from this repository
# IMPORTANT: Use -s user for personal tools you want available across all projects
# Without -s flag, servers are only available in current directory and are temporary

# Easy method: Use $(pwd) when in the project directory
cd /path/to/mcp-personal
claude mcp add file-search -s user -- $(pwd)/mcp_fd_server.py
claude mcp add fuzzy-search -s user -- $(pwd)/mcp_fuzzy_search.py
claude mcp add sqlite -s user -- $(pwd)/mcp_sqlite_server.py
claude mcp add sequential-thinking -s user -- $(pwd)/mcp_sequential_thinking.py

# Or use relative paths (also from project directory)
claude mcp add file-search -s user -- ./mcp_fd_server.py
claude mcp add fuzzy-search -s user -- ./mcp_fuzzy_search.py
claude mcp add sqlite -s user -- ./mcp_sqlite_server.py
claude mcp add sequential-thinking -s user -- ./mcp_sequential_thinking.py

# Using absolute paths (works from anywhere)
claude mcp add file-search -s user -- /path/to/mcp-personal/mcp_fd_server.py
claude mcp add fuzzy-search -s user -- /path/to/mcp-personal/mcp_fuzzy_search.py
claude mcp add sqlite -s user -- /path/to/mcp-personal/mcp_sqlite_server.py
claude mcp add sequential-thinking -s user -- /path/to/mcp-personal/mcp_sequential_thinking.py

# Disable thought logging for the sequential thinking server
claude mcp add sequential-thinking -s user -e DISABLE_THOUGHT_LOGGING=true -- /path/to/mcp-personal/mcp_sequential_thinking.py

# Add SQLite server with write permissions enabled
claude mcp add sqlite -s user -- /path/to/mcp-personal/mcp_sqlite_server.py --allow-writes

# Or using environment variable
claude mcp add sqlite -s user -e MCP_SQLITE_ALLOW_WRITES=true -- /path/to/mcp-personal/mcp_sqlite_server.py

# Add Python servers with Python interpreter explicitly
claude mcp add my-server -s user -- python /path/to/my_mcp_server.py

# Add servers with arguments
claude mcp add my-server -s user -- python /path/to/server.py arg1 arg2

# Add servers with environment variables
claude mcp add my-server -s user -e API_KEY=your_key -e DEBUG=true -- python /path/to/server.py

# Scope options:
# -s local (default): Temporary, only in current directory
# -s project: Shared with team via .mcp.json file
# -s user: Personal, available across all your projects (recommended)

{
  "mcpServers": {
    "file-search": {
      "command": "/path/to/mcp-personal/mcp_fd_server.py"
    },
    "fuzzy-search": {
      "command": "/path/to/mcp-personal/mcp_fuzzy_search.py"
    },
    "sqlite": {
      "command": "/path/to/mcp-personal/mcp_sqlite_server.py",
      "args": ["--allow-writes"],
      "env": {
        "MCP_SQLITE_ALLOW_WRITES": "true"
      }
    },
    "sequential-thinking": {
      "command": "/path/to/mcp-personal/mcp_sequential_thinking.py",
      "env": {
        "DISABLE_THOUGHT_LOGGING": "false"
      }
    }
  }
}

# Make all Python scripts executable
chmod +x *.py

# Install with development dependencies
uv sync --dev

# Or use make
make setup

# Test the file search server
npx @modelcontextprotocol/inspector ./mcp_fd_server.py

# Test the fuzzy search server  
npx @modelcontextprotocol/inspector ./mcp_fuzzy_search.py

# Test the SQLite server (read-only mode)
npx @modelcontextprotocol/inspector ./mcp_sqlite_server.py

# Test the SQLite server with write permissions
npx @modelcontextprotocol/inspector ./mcp_sqlite_server.py -- --allow-writes

# Test the sequential thinking server
npx @modelcontextprotocol/inspector ./mcp_sequential_thinking.py

# Test the sequential thinking server with thought logging disabled
npx @modelcontextprotocol/inspector -e "DISABLE_THOUGHT_LOGGING=true" ./mcp_sequential_thinking.py

# Using a config file
npx @modelcontextprotocol/inspector --config config.json

# Passing environment variables
npx @modelcontextprotocol/inspector -e "DEBUG=1" ./mcp_fuzzy_search.py

# Custom ports
npx @modelcontextprotocol/inspector --mcpp-port 3001 --mcpi-port 3002 ./mcp_fd_server.py

# Search for files by name pattern
./mcp_fd_server.py search "\.py$" /path/to/search  # Find Python files by name
./mcp_fd_server.py search "\.py$" . --limit 10  # Limit to first 10 results

# Search with additional fd flags
./mcp_fd_server.py search "\.js$" . --flags "--hidden --no-ignore"

# Fuzzy filter file names/paths
./mcp_fd_server.py filter "main" "\.py$" /path/to/search  # Fuzzy search for 'main' in Python file names
./mcp_fd_server.py filter "test" "" . --limit 20  # Find up to 20 test-related files

# Get the best fuzzy match by name
./mcp_fd_server.py filter "app" "" . --first  # Find file with name most similar to 'app'

# Multiline mode - search file CONTENTS (not just names)
./mcp_fd_server.py filter "class function" "" src --multiline  # Find files containing both terms
./mcp_fd_server.py filter "TODO" "" . --multiline --limit 5  # Find first 5 files with TODOs

# Fuzzy search for file NAMES/PATHS
./mcp_fuzzy_search.py search-files "main" /path/to/search  # Find files with 'main' in the name
./mcp_fuzzy_search.py search-files "test" . --hidden --limit 10  # Find test files by name
./mcp_fuzzy_search.py search-files "config" / --confirm-root  # Search from root (requires explicit confirmation)

# Search file CONTENTS and filter with fzf (NO regex support)
# Default: Matches on BOTH file paths AND content
# Works with both directories and individual files
./mcp_fuzzy_search.py search-content "TODO implement" .  # Find lines containing both terms
./mcp_fuzzy_search.py search-content "test.py: update" .  # Find 'update' in test.py files
./mcp_fuzzy_search.py search-content "function" specific_file.py  # Search within a single file
./mcp_fuzzy_search.py search-content "error handle" src --rg-flags "-i"  # Case insensitive
./mcp_fuzzy_search.py search-content "config" / --confirm-root  # Search from root (requires explicit confirmation)

# Content-only mode: Match ONLY on content, ignore file paths
./mcp_fuzzy_search.py search-content "TODO implement" . --content-only  # Pure content search
./mcp_fuzzy_search.py search-content "async await" src --content-only  # Won't match file paths

# Multiline mode - changes behavior:
# search-files --multiline: Searches file CONTENTS instead of names
./mcp_fuzzy_search.py search-files "class constructor" src --multiline  # Find files CONTAINING these terms

# search-content --multiline: Treats whole files as searchable units
./mcp_fuzzy_search.py search-content "async await" . --multiline  # Find files with both terms anywhere
./mcp_fuzzy_search.py search-content "try catch" . --multiline --content-only  # Content-only + multiline

# PDF and document search (requires optional binaries)
./mcp_fuzzy_search.py search-documents "machine learning" .  # Search PDFs and docs
./mcp_fuzzy_search.py search-documents "invoice total" invoices/ --file-types "pdf"  # PDFs only
./mcp_fuzzy_search.py search-documents "contract" . --file-types "pdf,docx" --limit 5
./mcp_fuzzy_search.py search-documents "report" / --confirm-root  # Search from root (requires explicit confirmation)

# Extract specific pages from PDFs (using PyMuPDF)
./mcp_fuzzy_search.py extract-pdf manual.pdf "1,3,5-7"  # Extract pages 1, 3, 5, 6, 7
./mcp_fuzzy_search.py extract-pdf report.pdf "v-vii,1,ToC"  # Use page labels
./mcp_fuzzy_search.py extract-pdf report.pdf "10-20" --format html  # Extract as HTML
./mcp_fuzzy_search.py extract-pdf thesis.pdf "100-105" --preserve-layout  # Keep layout
./mcp_fuzzy_search.py extract-pdf book.pdf "1-50" --fuzzy-hint "neural network"  # Filter by content
./mcp_fuzzy_search.py extract-pdf book.pdf "0,266-273" --zero-based  # 0-based indices (pages 1, 267-274)
./mcp_fuzzy_search.py extract-pdf book.pdf "1-50" --one-based  # 1-based indices (pages 1-50)

# Get PDF information
./mcp_fuzzy_search.py page-labels manual.pdf  # List all page labels
./mcp_fuzzy_search.py page-labels manual.pdf --start 100 --limit 20  # Get labels for pages 100-119
./mcp_fuzzy_search.py page-count manual.pdf  # Get total page count
./mcp_fuzzy_search.py pdf-outline manual.pdf  # Get table of contents
./mcp_fuzzy_search.py pdf-outline manual.pdf --max-depth 2  # Limit to 2 levels
./mcp_fuzzy_search.py pdf-outline manual.pdf --fuzzy-filter "chapter"  # Filter by title
./mcp_fuzzy_search.py pdf-outline manual.pdf --no-simple  # Detailed output with links

# Query database (read-only operations)
./mcp_sqlite_server.py query "SELECT * FROM users" database.db
./mcp_sqlite_server.py query "SELECT COUNT(*) as total FROM orders WHERE status = 'active'" sales.db

# List all tables
./mcp_sqlite_server.py list-tables database.db

# Describe table schema
./mcp_sqlite_server.py describe-table users database.db

# Execute write operations (requires --allow-writes flag)
./mcp_sqlite_server.py execute "INSERT INTO users (name, email) VALUES ('John', 'john@example.com')" database.db --allow-writes
./mcp_sqlite_server.py execute "UPDATE users SET active = 0 WHERE last_login < date('now', '-1 year')" database.db --allow-writes

# Use in-memory database for testing
./mcp_sqlite_server.py query "SELECT sqlite_version()" :memory:

# Run with thought logging disabled
DISABLE_THOUGHT_LOGGING=true ./mcp_sequential_thinking.py

# With --multiline, searches file CONTENTS instead of names
# Find files CONTAINING these terms (not in file names)
./mcp_fd_server.py filter "class constructor method" "" src --multiline

# Find Python files CONTAINING specific patterns  
./mcp_fd_server.py filter "class def return" "" . --multiline

# Find files CONTAINING database configuration
./mcp_fd_server.py filter "database host password" "" config --multiline

# search-files with --multiline searches file CONTENTS (not names)
./mcp_fuzzy_search.py search-files "async function await" src --multiline

# search-content with --multiline treats files as single units
./mcp_fuzzy_search.py search-content "try catch finally" . --multiline

# Find files CONTAINING class definitions with specific methods
./mcp_fuzzy_search.py search-content "class constructor render" src --multiline

# Find Python configuration files, excluding tests
config .py$ !test

# Find main files in src directory with multiple extensions  
^src/ main py$ | js$ | go$

# Find exact package manager files
'package.json' | 'yarn.lock' | 'Pipfile'

# Find TODO comments in code files, excluding documentation
TODO .py$ | .js$ | .go$ !README !docs/

# Find function definitions, excluding test files
'def ' .py$ !test !spec

# Find configuration files with specific extensions, excluding backups
config .json$ | .yaml$ | .toml$ !.bak$ !.old$

# Find implementation TODOs in specific file types
TODO implement .py: | .js:  # Matches TODO in .py or .js files

# Find error handling in specific files
error 'main.py:' | 'app.js:'  # Matches 'error' in main.py or app.js

# Find updates in test files
test.py: update  # Matches 'update' in files named test.py

# Find async functions with error handling
'async def' error .py$  # Matches in Python files

# With --content-only flag or content_only=true parameter
# These will ONLY match the content, not file names:

# Find TODO comments regardless of filename
TODO implement  # Won't match files named 'TODO.txt'

# Find async/await patterns
async await catch  # Pure content search

# Find class definitions
'class ' 'def __init__'  # Won't match 'class.py' filename

# Case-insensitive search with context in Python files
rg_flags: "-i -C 3 -t py"

# Search all files including hidden and ignored, with context
rg_flags: "-uu -C 2"

# Find exact function signatures in code files
rg_flags: "-F -w -t py -t js -t go"

# Search for TODOs with file types, case insensitive, show context
rg_flags: "-i -C 1 -t py -t js --no-ignore"

# Multi-line class definitions with context
rg_flags: "-U -C 3 -t py"

# Literal string search in all text files
rg_flags: "-F --no-ignore -t txt -t md -t rst"

{
  "pattern": r"\.py$",  # Find files with names ending in .py
  "path": "/home/user/projects",
  "flags": "--hidden --no-ignore"
}

{
  "filter": "test",  # Fuzzy match 'test' in file names
  "pattern": r"\.py$",  # Only Python files
  "path": "./src",
  "first": true
}

{
  "filter": "class function return",  # Find files containing all these terms
  "pattern": "",
  "path": "./src",
  "multiline": true  # Search CONTENTS, not names
}

{
  "fuzzy_filter": "main",  # Finds main.py, main.js, domain.py, etc.
  "path": "/home/user/projects",
  "hidden": true,
  "limit": 10
}

{
  "fuzzy_filter": "import export",  # Find files containing both terms
  "path": "./src",
  "multiline": true,  # Search CONTENTS, not names
  "limit": 5
}

{
  "fuzzy_filter": "test.py: TODO implement",  # Find TODOs in test.py files
  "path": "./src",
  "rg_flags": "-i",
  "limit": 15
}

{
  "fuzzy_filter": "function async",  # Find async functions in a specific file
  "path": "./src/main.py",  # Search within a single file
  "limit": 10
}

{
  "fuzzy_filter": "async await catch",  # Find these terms in content only
  "path": "./src",
  "content_only": true,  # Ignore file paths in matching
  "limit": 10
}

{
  "fuzzy_filter": "machine learning algorithm",
  "path": "./research",
  "file_types": "pdf,epub",
  "limit": 10
}

{
  "matches": [
    {
      "file": "/path/to/document.pdf",
      "line": 0,
      "content": "topology.",  # Content without "Page N: " prefix
      "match_text": "topology",
      "page": 542,  # 1-based page number (from ripgrep-all)
      "page_index_0based": 541,  # 0-based page index for programmatic access
      "page_label": "19"  # Actual PDF page label (only for PDFs with PyMuPDF)
    }
  ]
}

{
  "file": "research_paper.pdf",
  "pages": "v-vii,1,5-10,ToC",  # Mix of page labels and numbers
  "format": "markdown",
  "clean_html": true,
  "fuzzy_hint": "neural network"  # Only include pages mentioning this
}

# Example with zero_based=true
{
  "file": "research_paper.pdf",
  "pages": "0,266-273",  # Direct 0-based indices: page 1 and pages 267-274
  "zero_based": true
}

# Example with one_based=true
{
  "file": "research_paper.pdf",
  "pages": "1,267-274",  # Direct 1-based indices: pages 1, 267-274
  "one_based": true
}

{
  "file": "research_paper.pdf"
}

# Returns something like:
{
  "page_labels": {
    "0": "Cover",
    "1": "i",
    "2": "ii", 
    "3": "iii",
    "4": "iv",
    "5": "v",
    "6": "vi",
    "7": "vii",
    "8": "viii",
    "9": "1",
    "10": "2",
    "11": "3"
  },
  "page_count": 150
}

# Example with slicing:
{
  "file": "research_paper.pdf",
  "start": 100,
  "limit": 20
}

# Returns subset like:
{
  "page_labels": {
    "100": "87",
    "101": "88",
    "102": "89",
    "103": "90",
    "104": "91"
    # ... up to 20 entries
  },
  "page_count": 150
}

{
  "file": "research_paper.pdf"
}

# Returns:
{
  "page_count": 150
}

{
  "file": "research_paper.pdf"
}

# Returns (simple mode):
{
  "outline": [
    [1, "Introduction", 1, "i"],
    [1, "Chapter 1: Background", 5, "1"],
    [2, "1.1 History", 6, "2"],
    [2, "1.2 Related Work", 10, "6"],
    [1, "Chapter 2: Methods", 15, "11"],
    [2, "2.1 Data Collection", 16, "12"],
    [3, "2.1.1 Sources", 17, "13"],
    [2, "2.2 Analysis", 20, "16"]
  ],
  "total_entries": 8,
  "max_depth_found": 3
}

# Example with filtering:
{
  "file": "research_paper.pdf",
  "fuzzy_filter": "chapter"
}

# Returns:
{
  "outline": [
    [1, "Chapter 1: Background", 5, "1"],
    [1, "Chapter 2: Methods", 15, "11"]
  ],
  "total_entries": 8,
  "max_depth_found": 3,
  "filtered_count": 2
}

# Example with detailed output:
{
  "file": "research_paper.pdf",
  "simple": false,
  "max_depth": 2
}

# Returns:
{
  "outline": [
    [1, "Introduction", 1, "i", {
      "page": 1,
      "uri": "#page=1&zoom=100,0,0",
      "is_external": false,
      "is_open": true,
      "dest": {
        "kind": 1,
        "page": 0,
        "uri": "#page=1&zoom=100,0,0"
      }
    }],
    # ... more entries with link details
  ],
  "total_entries": 8,
  "max_depth_found": 2
}

{
  "query": "SELECT * FROM users WHERE active = 1 ORDER BY created_at DESC LIMIT 10",
  "db_path": "myapp.db"
}

{
  "query": "UPDATE users SET last_login = datetime('now') WHERE id = 123",
  "db_path": "myapp.db"
}

{
  "db_path": "myapp.db"
}

{
  "table_name": "users",
  "db_path": "myapp.db"
}

{
  "table_name": "sessions",
  "columns": [
    {
      "name": "id",
      "type": "TEXT",
      "constraints": "PRIMARY KEY"
    },
    {
      "name": "user_id",
      "type": "INTEGER",
      "constraints": "NOT NULL"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "constraints": "DEFAULT CURRENT_TIMESTAMP"
    },
    {
      "name": "expires_at",
      "type": "TIMESTAMP",
      "constraints": "NOT NULL"
    }
  ],
  "db_path": "myapp.db"
}

{
  "thought": "First, I need to map out the failure modes before proposing a fix.",
  "nextThoughtNeeded": true,
  "thoughtNumber": 1,
  "totalThoughts": 5
}

{
  "thought": "Reconsidering thought 2 — the retry logic is actually the root cause, not the timeout.",
  "nextThoughtNeeded": true,
  "thoughtNumber": 4,
  "totalThoughts": 6,
  "isRevision": true,
  "revisesThought": 2
}

{
  "thought": "Alternative approach: skip the cache entirely and hit the DB directly.",
  "nextThoughtNeeded": true,
  "thoughtNumber": 5,
  "totalThoughts": 7,
  "branchFromThought": 3,
  "branchId": "no-cache"
}

mcp-personal/
├── mcp_fd_server.py            # File search MCP server
├── mcp_fuzzy_search.py         # Fuzzy content search MCP server
├── mcp_sqlite_server.py        # SQLite database MCP server
├── mcp_sequential_thinking.py  # Sequential thinking MCP server
├── tests/                      # Test suite
│   ├── test_simple.py          # Direct function tests
│   ├── test_fd_server.py       # File search MCP integration tests
│   ├── test_fuzzy_search.py    # Fuzzy search tests
│   ├── test_sqlite_server.py   # SQLite server tests
│   ├── test_sequential_thinking.py # Sequential thinking tests
│   └── test_cli.py             # CLI interface tests
├── pyproject.toml        # Project configuration
├── Makefile              # Development commands
├── CLAUDE.md             # Claude-specific instructions
└── README.md             # This file

# Run all tests
make test

# Run specific test categories
make test-simple  # Direct function tests
make test-cli     # CLI interface tests
make test-full    # Full MCP integration tests

# Run with coverage
make test-cov

make help         # Show all available commands
make setup        # Install development dependencies
make test         # Run tests
make lint         # Run linting
make format       # Format code
make type-check   # Run type checking
make clean        # Clean generated files