Claude Code & IDEs: Wiring MCP into Your Dev Environment

#!/usr/bin/env python3
"""Minimal stdio MCP server — entry point for .claude/settings.json."""
import os
from mcp.server.fastmcp import FastMCP

# FastMCP handles JSON-RPC negotiation and stdio transport automatically
mcp = FastMCP("my-tools")

@mcp.tool()
def ping(message: str) -> str:
    """Echo a message back with server identity. Useful for testing connectivity."""
    db_url = os.environ.get("DB_URL", "not set")  # env var from settings.json
    return f"pong: {message} (db={db_url})"

if __name__ == "__main__":
    # run() starts the stdio loop — blocks until Claude Code closes the process
    mcp.run()

#!/usr/bin/env python3
"""MCP server over HTTP/SSE — use url: in settings.json to connect."""
import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-tools")

@mcp.tool()
def status() -> dict:
    """Return deployment status. Callable from any IDE pointing at this URL."""
    return {"status": "ok", "version": "1.0.0"}

if __name__ == "__main__":
    # sse transport starts an HTTP server; point settings.json "url" at /sse
    mcp.run(transport="sse", host="0.0.0.0", port=8080)

#!/usr/bin/env python3
"""
Personal Productivity MCP Server — 6 hardened dev tools.
Configure in ~/.claude/settings.json or claude_desktop_config.json:

  "personal-tools": {
    "command": "python",
    "args": ["/absolute/path/to/personal_server.py"],
    "env": { "PROJECTS_ROOT": "/home/you/projects" }
  }
"""
import os
import re
import subprocess
import sqlite3
import urllib.request
from pathlib import Path
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("personal-tools")

# ── Security baseline ──────────────────────────────────────────────────────
PROJECTS_ROOT = Path(os.environ.get("PROJECTS_ROOT", Path.home() / "projects")).resolve()
MAX_OUTPUT = 20_000  # chars — prevent context flooding

def _safe_path(raw: str) -> Path:
    """Resolve path and assert it stays inside PROJECTS_ROOT."""
    p = (PROJECTS_ROOT / raw).resolve()
    try:
        p.relative_to(PROJECTS_ROOT)  # raises ValueError if outside
        return p
    except ValueError:
        raise PermissionError(f"Path '{raw}' escapes PROJECTS_ROOT. Allowed root: {PROJECTS_ROOT}")

def _truncate(text: str) -> str:
    if len(text) > MAX_OUTPUT:
        return text[:MAX_OUTPUT] + f"\n\n[... truncated at {MAX_OUTPUT} chars ...]"
    return text

# ── Tool 1: run_tests ──────────────────────────────────────────────────────
@mcp.tool()
def run_tests(
    directory: str,
    framework: str = "pytest",
    extra_args: str = "",
) -> str:
    """
    Run pytest or jest in a project directory and return stdout + exit code.
    directory: path relative to PROJECTS_ROOT.
    framework: 'pytest' or 'jest'.
    extra_args: additional flags (e.g. '-k test_login' or '--testPathPattern=auth').
    """
    target = _safe_path(directory)
    if not target.is_dir():
        return f"ERROR: '{directory}' is not a directory inside PROJECTS_ROOT."

    if framework == "pytest":
        cmd = ["python", "-m", "pytest", "--tb=short", "-q"] + (extra_args.split() if extra_args else [])
    elif framework == "jest":
        cmd = ["npx", "jest", "--no-coverage"] + (extra_args.split() if extra_args else [])
    else:
        return f"ERROR: unknown framework '{framework}'. Use 'pytest' or 'jest'."

    try:
        result = subprocess.run(
            cmd,
            cwd=str(target),
            capture_output=True,
            text=True,
            timeout=120,
        )
        output = (result.stdout + result.stderr).strip()
        return _truncate(f"Exit code: {result.returncode}\n\n{output}")
    except subprocess.TimeoutExpired:
        return "ERROR: Test run timed out after 120 seconds."
    except FileNotFoundError as e:
        return f"ERROR: Command not found — {e}. Is {framework} installed?"

# ── Tool 2: search_codebase ────────────────────────────────────────────────
@mcp.tool()
def search_codebase(
    pattern: str,
    directory: str = ".",
    file_glob: str = "",
    max_results: int = 50,
) -> str:
    """
    Search files using ripgrep (rg). Returns matching lines with file:line context.
    pattern: regex or literal string to search.
    directory: path relative to PROJECTS_ROOT (default: PROJECTS_ROOT itself).
    file_glob: optional glob filter e.g. '*.py' or '**/*.ts'.
    max_results: cap on returned matches (default 50).
    """
    target = _safe_path(directory)
    cmd = ["rg", "--line-number", "--no-heading", f"--max-count={max_results}", pattern, str(target)]
    if file_glob:
        cmd += ["--glob", file_glob]

    try:
        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
        if result.returncode == 1:  # rg exit 1 = no matches (not an error)
            return f"No matches for pattern '{pattern}' in '{directory}'."
        if result.returncode > 1:
            return f"ERROR running ripgrep: {result.stderr.strip()}"
        return _truncate(result.stdout.strip())
    except FileNotFoundError:
        return "ERROR: 'rg' (ripgrep) not found. Install: https://github.com/BurntSushi/ripgrep"
    except subprocess.TimeoutExpired:
        return "ERROR: Search timed out after 30 seconds."

# ── Tool 3: read_docs ──────────────────────────────────────────────────────
@mcp.tool()
def read_docs(url: str) -> str:
    """
    Fetch a URL and return its text content (HTML stripped to plain text).
    url: must start with http:// or https://.
    """
    if not url.startswith(("http://", "https://")):
        return "ERROR: URL must start with http:// or https://"

    try:
        req = urllib.request.Request(url, headers={"User-Agent": "mcp-personal-tools/1.0"})
        with urllib.request.urlopen(req, timeout=15) as resp:
            raw = resp.read().decode("utf-8", errors="replace")
        # Strip HTML tags crudely — good enough for docs
        text = re.sub(r"<[^>]+>", " ", raw)
        text = re.sub(r"\s{3,}", "\n\n", text).strip()
        return _truncate(text)
    except urllib.error.URLError as e:
        return f"ERROR fetching '{url}': {e}"
    except Exception as e:
        return f"ERROR: {type(e).__name__}: {e}"

# ── Tool 4: get_git_log ────────────────────────────────────────────────────
@mcp.tool()
def get_git_log(directory: str = ".", n: int = 20) -> str:
    """
    Return the last N git commit messages with hashes and authors.
    directory: path relative to PROJECTS_ROOT.
    n: number of commits to return (default 20, max 100).
    """
    target = _safe_path(directory)
    n = min(max(1, n), 100)  # clamp 1..100

    try:
        result = subprocess.run(
            ["git", "log", f"-{n}", "--pretty=format:%h %ae %s", "--no-merges"],
            cwd=str(target),
            capture_output=True,
            text=True,
            timeout=10,
        )
        if result.returncode != 0:
            return f"ERROR: git log failed — {result.stderr.strip()}"
        return result.stdout.strip() or "No commits found."
    except FileNotFoundError:
        return "ERROR: git not found in PATH."
    except subprocess.TimeoutExpired:
        return "ERROR: git log timed out."

# ── Tool 5: check_env ─────────────────────────────────────────────────────
@mcp.tool()
def check_env(pattern: str = "") -> str:
    """
    List environment variable NAMES matching a pattern.
    Returns names only — never values. Safe to call freely.
    pattern: case-insensitive substring filter (empty = return all names).
    """
    names = sorted(os.environ.keys())
    if pattern:
        names = [n for n in names if pattern.upper() in n.upper()]
    if not names:
        return f"No environment variables match pattern '{pattern}'."
    return "\n".join(names) + f"\n\n({len(names)} variable(s) found — values intentionally hidden)"

# ── Tool 6: run_sql ───────────────────────────────────────────────────────
@mcp.tool()
def run_sql(db_path: str, query: str) -> str:
    """
    Run a read-only SQL query against a SQLite database file.
    db_path: path relative to PROJECTS_ROOT.
    query: must start with SELECT (no mutations allowed).
    """
    safe_db = _safe_path(db_path)
    if not safe_db.exists():
        return f"ERROR: Database '{db_path}' not found inside PROJECTS_ROOT."

    # Enforce read-only: allow SELECT and WITH (CTEs) only
    stripped = query.strip().upper()
    if not (stripped.startswith("SELECT") or stripped.startswith("WITH")):
        return "ERROR: Only SELECT queries are permitted. No INSERT/UPDATE/DELETE/DROP/CREATE."

    try:
        con = sqlite3.connect(f"file:{safe_db}?mode=ro", uri=True)
        con.row_factory = sqlite3.Row
        cursor = con.execute(query)
        rows = cursor.fetchmany(500)  # hard cap
        if not rows:
            return "Query returned 0 rows."
        headers = list(rows[0].keys())
        lines = [" | ".join(headers), "-" * 60]
        for row in rows:
            lines.append(" | ".join(str(v) for v in row))
        con.close()
        return _truncate("\n".join(lines))
    except sqlite3.OperationalError as e:
        return f"SQL ERROR: {e}"
    finally:
        try:
            con.close()
        except Exception:
            pass

if __name__ == "__main__":
    mcp.run()