mcp-methods 0.1.1__tar.gz

mcp_methods-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,126 @@
+name: Build and Publish Python Package
+
+on:
+  push:
+    paths:
+      - 'pyproject.toml'
+      - 'mcp_methods/**'
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  version:
+    name: Extract version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from pyproject.toml
+        id: get_version
+        run: |
+          VERSION=$(grep -m 1 "version" pyproject.toml | cut -d '"' -f 2)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Package version: $VERSION"
+
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v
+
+      - name: Test import
+        run: |
+          python -c "from mcp_methods import git_issue, git_api, grep_files, read_file, ElementCache; print('Import successful')"
+
+  build:
+    name: Build distribution
+    needs: [version, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution
+        run: twine check dist/*
+
+      - name: List distribution files
+        run: ls -lh dist/
+
+      - name: Upload distribution as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: [version, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write  # Required for trusted publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Display structure of downloaded files
+        run: ls -lh dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+          # Uncomment to test on TestPyPI first
+          # repository-url: https://test.pypi.org/legacy/
+
+      - name: Checkout code for release
+        uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          tag_name: v${{ needs.version.outputs.version }}
+          name: Release v${{ needs.version.outputs.version }}
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mcp_methods-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristian Kollsgard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_methods-0.1.1/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: mcp-methods
+Version: 0.1.1
+Summary: Reusable utility methods for MCP servers
+Author: Kristian Kollsgard
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,github,mcp,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-methods
+
+Reusable utility methods for MCP servers. Extracts common patterns from MCP server implementations into a shared, pip-installable library.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from mcp_methods import git_issue, git_api, grep_files, read_file, ElementCache
+
+# GitHub API
+result = git_api("pydata/xarray", "pulls?state=open")
+
+# Fetch issue/PR with smart compaction
+cache = ElementCache()
+result = git_issue("pydata/xarray", 11124, cache=cache)
+
+# Search files
+result = grep_files(["/path/to/source"], "pattern", glob="*.py")
+
+# Read file with path traversal protection
+result = read_file("src/main.py", ["/path/to/source"])
+```

mcp_methods-0.1.1/README.md

@@ -0,0 +1,28 @@
+# mcp-methods
+
+Reusable utility methods for MCP servers. Extracts common patterns from MCP server implementations into a shared, pip-installable library.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from mcp_methods import git_issue, git_api, grep_files, read_file, ElementCache
+
+# GitHub API
+result = git_api("pydata/xarray", "pulls?state=open")
+
+# Fetch issue/PR with smart compaction
+cache = ElementCache()
+result = git_issue("pydata/xarray", 11124, cache=cache)
+
+# Search files
+result = grep_files(["/path/to/source"], "pattern", glob="*.py")
+
+# Read file with path traversal protection
+result = read_file("src/main.py", ["/path/to/source"])
+```

mcp_methods-0.1.1/mcp_methods/__init__.py

@@ -0,0 +1,27 @@
+"""mcp-methods: Reusable utility methods for MCP servers."""
+
+from mcp_methods._utils import load_env, timed
+from mcp_methods.files import grep_files, read_file
+from mcp_methods.git import (
+    ElementCache,
+    detect_git_repo,
+    extract_github_refs,
+    git_api,
+    git_issue,
+    has_git_token,
+    validate_repo,
+)
+
+__all__ = [
+    "timed",
+    "load_env",
+    "git_api",
+    "git_issue",
+    "ElementCache",
+    "detect_git_repo",
+    "validate_repo",
+    "has_git_token",
+    "extract_github_refs",
+    "grep_files",
+    "read_file",
+]

mcp_methods-0.1.1/mcp_methods/_utils.py

@@ -0,0 +1,50 @@
+"""Shared utilities for MCP method libraries."""
+
+from __future__ import annotations
+
+import functools
+import os
+import time
+from pathlib import Path
+from typing import Callable
+
+
+def timed(func: Callable) -> Callable:
+    """Decorator that appends timing info to string return values.
+
+    Usage::
+
+        @timed
+        def my_tool(...) -> str:
+            ...
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        t0 = time.perf_counter()
+        result = func(*args, **kwargs)
+        ms = (time.perf_counter() - t0) * 1000
+        return result + f"\n\n⏱ {ms:.0f}ms"
+
+    return wrapper
+
+
+def load_env(env_file: str | Path) -> None:
+    """Load key=value pairs from a .env file into ``os.environ``.
+
+    - Blank lines and lines starting with ``#`` are skipped.
+    - Values may be optionally quoted with single or double quotes.
+    - Existing environment variables are **not** overwritten.
+    """
+    path = Path(env_file)
+    if not path.exists():
+        return
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key = key.strip()
+        val = val.strip().strip("'\"")
+        if key and key not in os.environ:
+            os.environ[key] = val

mcp_methods-0.1.1/mcp_methods/files.py

@@ -0,0 +1,178 @@
+"""File search and reading methods for MCP servers."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Callable
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_SKIP_DIRS: set[str] = {
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+    ".eggs",
+    "venv",
+    ".venv",
+    "target",
+    ".cargo",
+    ".ruff_cache",
+}
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def grep_files(
+    source_dirs: list[str | Path],
+    pattern: str,
+    *,
+    glob: str = "*",
+    case_insensitive: bool = False,
+    max_results: int = 50,
+    skip_dirs: set[str] | None = None,
+    relative_to: str | Path | None = None,
+    transform: Callable[[str], str] | None = None,
+) -> str:
+    """Search for a text pattern across files in *source_dirs*.
+
+    *source_dirs*: directories to search (recursively).
+    *pattern*: plain text or regex pattern to search for.
+    *glob*: file glob to filter (default ``"*"`` for all files).
+    *case_insensitive*: set True for case-insensitive matching.
+    *max_results*: maximum number of matching lines to return.
+    *skip_dirs*: directory names to skip (defaults to :data:`DEFAULT_SKIP_DIRS`).
+    *relative_to*: if set, display paths relative to this directory.
+    *transform*: optional function to transform file content before searching
+        (e.g. HTML-to-text converter).
+    """
+    try:
+        flags = re.IGNORECASE if case_insensitive else 0
+        regex = re.compile(pattern, flags)
+    except re.error as e:
+        return f"Invalid regex pattern: {e}"
+
+    if skip_dirs is None:
+        skip_dirs = DEFAULT_SKIP_DIRS
+
+    rel_base = Path(relative_to) if relative_to else None
+
+    matches: list[str] = []
+    for source_dir in source_dirs:
+        source_dir = Path(source_dir)
+        if not source_dir.is_dir():
+            continue
+        for path in sorted(source_dir.rglob(glob)):
+            if not path.is_file():
+                continue
+            if any(part in skip_dirs for part in path.parts):
+                continue
+            try:
+                if rel_base:
+                    rel = str(path.relative_to(rel_base))
+                else:
+                    rel = str(path.relative_to(source_dir))
+                text = path.read_text(encoding="utf-8")
+                if transform:
+                    text = transform(text)
+                for i, line in enumerate(text.splitlines(), 1):
+                    if regex.search(line):
+                        matches.append(f"  {rel}:{i}  {line.rstrip()}")
+                        if len(matches) >= max_results:
+                            break
+            except (UnicodeDecodeError, PermissionError):
+                continue
+            if len(matches) >= max_results:
+                break
+        if len(matches) >= max_results:
+            break
+
+    if not matches:
+        return f"No matches for '{pattern}' in {glob} files."
+    header = f"Found {len(matches)} match(es) for '{pattern}'"
+    if len(matches) >= max_results:
+        header += f" (capped at {max_results})"
+    return header + ":\n" + "\n".join(matches)
+
+
+def read_file(
+    file_path: str,
+    allowed_dirs: list[str | Path],
+    *,
+    start_line: int | None = None,
+    end_line: int | None = None,
+    max_chars: int | None = None,
+    transform: Callable[[str], str] | None = None,
+) -> str:
+    """Read a file with path-traversal protection.
+
+    *file_path*: relative path resolved against each directory in *allowed_dirs*.
+    *allowed_dirs*: directories in which the file must reside (path traversal guard).
+    *start_line*: first line to include (1-indexed).
+    *end_line*: last line to include (1-indexed, inclusive).
+    *max_chars*: truncate the result to this many characters.
+    *transform*: optional function to transform file content before returning
+        (e.g. HTML-to-text converter).
+    """
+    # Resolve file against allowed directories
+    resolved: Path | None = None
+    base_dir: Path | None = None
+    for d in allowed_dirs:
+        d = Path(d)
+        candidate = (d / file_path).resolve()
+        if candidate.is_relative_to(d.resolve()) and candidate.exists():
+            resolved = candidate
+            base_dir = d
+            break
+
+    if resolved is None:
+        # Check if it's an absolute path inside an allowed dir
+        abs_path = Path(file_path).resolve()
+        for d in allowed_dirs:
+            d = Path(d)
+            if abs_path.is_relative_to(d.resolve()) and abs_path.exists():
+                resolved = abs_path
+                base_dir = d
+                break
+
+    if resolved is None:
+        return f"Error: file not found or access denied: {file_path}"
+
+    try:
+        raw = resolved.read_text(encoding="utf-8")
+    except Exception as e:
+        return f"Error reading file: {e}"
+
+    # Apply transform (e.g. HTML to text)
+    if transform:
+        raw = transform(raw)
+
+    all_lines = raw.splitlines()
+    total = len(all_lines)
+
+    if start_line is not None or end_line is not None:
+        s = max(1, start_line or 1)
+        e = min(total, end_line or total)
+        selected = all_lines[s - 1 : e]
+        numbered = [f"{i:>5}  {line}" for i, line in enumerate(selected, start=s)]
+        header = f"{file_path}:{s}-{e}  ({e - s + 1} of {total} lines)"
+    else:
+        selected = all_lines
+        numbered = [f"{i:>5}  {line}" for i, line in enumerate(selected, start=1)]
+        header = f"{file_path}  ({total} lines)"
+
+    text = header + "\n" + "\n".join(numbered)
+
+    if max_chars and len(text) > max_chars:
+        text = text[:max_chars] + f"\n\n[... truncated at {max_chars} chars — {len(raw)} total]"
+
+    return text