Add GitHub Actions test workflow

Author: sebthom

.github/workflows/test.yml

@@ -0,0 +1,70 @@
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: Tests
+
+on:  # https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+  push:
+    branches-ignore:  # build all branches except:
+    - 'dependabot/**'  # prevent GHA triggered twice (once for commit to the branch and once for opening/syncing the PR)
+    tags-ignore:  # don't build tags
+    - '**'
+    paths-ignore:
+    - '**/*.md'
+  pull_request:
+    paths-ignore:
+    - '**/*.md'
+  workflow_dispatch:
+    # https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+      fail-fast: false
+
+    steps:
+    - name: Git Checkout
+      uses: actions/checkout@v4  # https://github.com/actions/checkout
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install
+
+    - name: Install ast-grep
+      run: |
+        npm install -g @ast-grep/cli
+        ast-grep --version
+
+    - name: Install dependencies
+      run: |
+        uv sync --all-extras --dev
+
+    - name: Lint with ruff
+      run: |
+        uv run ruff check .
+
+    - name: Format check with ruff
+      run: |
+        uv run ruff format --check .
+      continue-on-error: true  # TODO
+
+    - name: Type check with mypy
+      run: |
+        uv run mypy main.py
+
+    - name: Run unit tests
+      run: |
+        uv run pytest tests/test_main.py -v --cov=main --cov-report=term-missing
+
+    - name: Run integration tests
+      run: |
+        uv run pytest tests/test_integration.py -v

.gitignore

@@ -6,5 +6,8 @@ dist/
 wheels/
 *.egg-info
 
+# MyPy. Ruff, PyTest cache folders
+.*_cache/
+
 # Virtual environments
 .venv

main.py

@@ -1,54 +1,59 @@
-from typing import Any, List, Optional
-from mcp.server.fastmcp import FastMCP
-import subprocess
-from pydantic import Field
-import json
-from enum import Enum
 import argparse
+import json
 import os
+import subprocess
 import sys
+from enum import Enum
+from typing import Any, List, Optional
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
 
-# Determine how the script was invoked
-if sys.argv[0].endswith('main.py'):
-    # Direct execution: python main.py
-    prog = 'python main.py'
-else:
-    # Installed script execution (via uvx, pip install, etc.)
-    prog = None  # Let argparse use the default
-
-# Parse command-line arguments
-parser = argparse.ArgumentParser(
-    prog=prog,
-    description='ast-grep MCP Server - Provides structural code search capabilities via Model Context Protocol',
-    epilog='''
+# Global variable for config path (will be set by parse_args_and_get_config)
+CONFIG_PATH = None
+
+def parse_args_and_get_config():
+    """Parse command-line arguments and determine config path."""
+    global CONFIG_PATH
+
+    # Determine how the script was invoked
+    prog = None
+    if sys.argv[0].endswith('main.py'):
+        # Direct execution: python main.py
+        prog = 'python main.py'
+
+    # Parse command-line arguments
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description='ast-grep MCP Server - Provides structural code search capabilities via Model Context Protocol',
+        epilog='''
 environment variables:
   AST_GREP_CONFIG    Path to sgconfig.yaml file (overridden by --config flag)
 
 For more information, see: https://github.com/ast-grep/ast-grep-mcp
-    ''',
-    formatter_class=argparse.RawDescriptionHelpFormatter
-)
-parser.add_argument(
-    '--config',
-    type=str,
-    metavar='PATH',
-    help='Path to sgconfig.yaml file for customizing ast-grep behavior (language mappings, rule directories, etc.)'
-)
-args = parser.parse_args()
-
-# Determine config path with precedence: --config flag > AST_GREP_CONFIG env > None
-CONFIG_PATH = None
-if args.config:
-    if not os.path.exists(args.config):
-        print(f"Error: Config file '{args.config}' does not exist")
-        sys.exit(1)
-    CONFIG_PATH = args.config
-elif os.environ.get('AST_GREP_CONFIG'):
-    env_config = os.environ.get('AST_GREP_CONFIG')
-    if not os.path.exists(env_config):
-        print(f"Error: Config file '{env_config}' specified in AST_GREP_CONFIG does not exist")
-        sys.exit(1)
-    CONFIG_PATH = env_config
+        ''',
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        '--config',
+        type=str,
+        metavar='PATH',
+        help='Path to sgconfig.yaml file for customizing ast-grep behavior (language mappings, rule directories, etc.)'
+    )
+    args = parser.parse_args()
+
+    # Determine config path with precedence: --config flag > AST_GREP_CONFIG env > None
+    if args.config:
+        if not os.path.exists(args.config):
+            print(f"Error: Config file '{args.config}' does not exist")
+            sys.exit(1)
+        CONFIG_PATH = args.config
+    elif os.environ.get('AST_GREP_CONFIG'):
+        env_config = os.environ.get('AST_GREP_CONFIG')
+        if env_config and not os.path.exists(env_config):
+            print(f"Error: Config file '{env_config}' specified in AST_GREP_CONFIG does not exist")
+            sys.exit(1)
+        CONFIG_PATH = env_config
 
 # Initialize FastMCP server
 mcp = FastMCP("ast-grep")
@@ -62,7 +67,7 @@ class DumpFormat(Enum):
 def dump_syntax_tree(
     code: str = Field(description = "The code you need"),
     language: str = Field(description = "The language of the code"),
-    format: DumpFormat = Field(description = "Code dump format. Available values: pattern, ast, cst", default = "cst"),
+    format: DumpFormat = Field(description = "Code dump format. Available values: pattern, ast, cst", default = DumpFormat.CST),
 ) -> str:
     """
     Dump code's syntax structure or dump a query's pattern structure.
@@ -75,7 +80,7 @@ def dump_syntax_tree(
     Internally calls: ast-grep run --pattern <code> --lang <language> --debug-query=<format>
     """
     result = run_ast_grep("run", ["--pattern", code, "--lang", language, f"--debug-query={format.value}"])
-    return result.stderr.strip()
+    return result.stderr.strip()  # type: ignore[no-any-return]
 
 @mcp.tool()
 def test_match_code_rule(
@@ -92,7 +97,7 @@ def test_match_code_rule(
     matches = json.loads(result.stdout.strip())
     if not matches:
         raise ValueError("No matches found for the given code and rule. Try adding `stopBy: end` to your inside/has rule.")
-    return matches
+    return matches  # type: ignore[no-any-return]
 
 @mcp.tool()
 def find_code(
@@ -131,7 +136,7 @@ def find_code(
         # Limit results if max_results is specified
         if max_results is not None and len(matches) > max_results:
             matches = matches[:max_results]
-        return matches
+        return matches  # type: ignore[no-any-return]
     else:
         # Text format - return plain text output
         result = run_ast_grep("run", args + [project_folder])
@@ -150,7 +155,7 @@ def find_code(
             else:
                 header = f"Found {len(non_empty_lines)} matches:\n"
             output = header + output
-        return output
+        return output  # type: ignore[no-any-return]
 
 @mcp.tool()
 def find_code_by_rule(
@@ -188,7 +193,7 @@ def find_code_by_rule(
         # Limit results if max_results is specified
         if max_results is not None and len(matches) > max_results:
             matches = matches[:max_results]
-        return matches
+        return matches  # type: ignore[no-any-return]
     else:
         # Text format - return plain text output
         result = run_ast_grep("scan", args + [project_folder])
@@ -207,16 +212,21 @@ def find_code_by_rule(
             else:
                 header = f"Found {len(non_empty_lines)} matches:\n"
             output = header + output
-        return output
+        return output  # type: ignore[no-any-return]
 
 def run_command(args: List[str], input_text: Optional[str] = None) -> subprocess.CompletedProcess:
     try:
+        # On Windows, if ast-grep is installed via npm, it's a batch file
+        # that requires shell=True to execute properly
+        use_shell = (sys.platform == "win32" and args[0] == "ast-grep")
+
         result = subprocess.run(
             args,
             capture_output=True,
             input=input_text,
             text=True,
-            check=True  # Raises CalledProcessError if return code is non-zero
+            check=True,  # Raises CalledProcessError if return code is non-zero
+            shell=use_shell
         )
         return result
     except subprocess.CalledProcessError as e:
@@ -237,6 +247,7 @@ def run_mcp_server() -> None:
     Run the MCP server.
     This function is used to start the MCP server when this script is run directly.
     """
+    parse_args_and_get_config()
     mcp.run(transport="stdio")
 
 if __name__ == "__main__":

pyproject.toml

@@ -9,5 +9,49 @@ dependencies = [
     "mcp[cli]>=1.6.0",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.7.0",
+    "mypy>=1.13.0",
+]
+
 [project.scripts]
 ast-grep-server = "main:run_mcp_server"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v"
+
+[tool.coverage.run]
+source = ["main"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+    "pass",
+    "except ImportError:",
+]
+
+[tool.ruff]
+line-length = 140
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true

tests/fixtures/example.py

@@ -0,0 +1,11 @@
+def hello():
+    print("Hello, World!")
+
+
+def add(a, b):
+    return a + b
+
+
+class Calculator:
+    def multiply(self, x, y):
+        return x * y