following @HerringtonDarkholme issue 3 - Add MCP to help model learn the tool!

[georgiedekker]

Enhanced ast-grep MCP Server: New Tools, Resources, and fastmcp Migration

This pull request significantly enhances the ast-grep-mcp server by introducing new tools, resource handling, and migrating to the fastmcp library. The primary goal was to implement features outlined in Issue #3, making the server more comprehensive and robust for use with MCP clients like Cursor.

Key Changes:

1. Library Migration & Error Handling

• fastmcp Integration: The server has been migrated from the original mcp library to fastmcp. This involved:
  • Updating dependencies in pyproject.toml.
  • Refactoring main.py to use fastmcp conventions, including its resource definition mechanisms.
• Simplified Error Handling: Error handling was subsequently simplified to use standard Python exceptions (e.g., ValueError, RuntimeError, FileNotFoundError) for easier maintenance. fastmcp is now responsible for translating these into appropriate JSON-RPC error responses.

2. New Tools Implemented (Addressing Issue #3)

• Rule Management:
  • list_rules(project_folder): Lists YAML rule files in the project's sg_rules directory.
  • get_rule(project_folder, rule_name): Retrieves the content of a specific YAML rule file.
  • create_new_rule(project_folder, rule_name, rule_content): Creates a new YAML rule file with basic YAML syntax validation.
• AST & Rule Diagnostics:
  • dump_ast(code, language): (Already present in base) Dumps the AST structure of a given code snippet.
  • validate_rule_syntax(rule): (Already present in base) Validates the YAML syntax of an ast-grep rule.
  • list_all_diagnostics_in_the_workspace(project_folder): Runs ast-grep scan using rules in the sg_rules directory and returns any found diagnostics.
• Language Information:
  • get_supported_languages(): (Already present in base) Returns a list of languages supported by ast-grep.
  • get_language_kinds(language): (Already present in base) Returns AST node kinds for a specified language.
• Code Search:
  • find_code(project_folder, pattern, language): (Already present in base) Finds code using a simple pattern.
  • find_code_by_rule(project_folder, yaml): (Already present in base) Finds code using a YAML rule.

3. Resource Implementation (Addressing Issue #3)

The server now implements MCP resources to expose rule files and mock test data:

• Local Rules:
  • rule://sg_rules: Lists local rule files in the sg_rules directory of the specified project_folder.
  • rule://sg_rules/{rule_name}: Provides access to the content of a specific local rule file.
• Mock Global Rule:
  • rule://global/example-global-rule.yml: A static resource providing example content for a hypothetical global rule.
• Mock Test Cases:
  • testcase://python/example-test.py: A static resource with example Python code.
  • testcase://javascript/example-test.js: A static resource with example JavaScript code.

4. Error Handling Enhancements

• Improved error handling throughout the tools and subprocess calls to provide more specific feedback (e.g., for invalid project folders, missing files, command failures).

5. Dockerfile

• A Dockerfile was introduced and refined to build a containerized version of the ast-grep-mcp server. This involved:
  • Installing uv and using it for Python environment and package management.
  • Installing ast-grep-cli.
  • Copying project files and installing dependencies from pyproject.toml and uv.lock.
  • Resolving various path and dependency issues during the build process.

Implementation Status of Issue #3 Items:

Implemented:

• resources: Implemented through the @mcp.resource handlers for rules and mock test cases.
• rules: Specifically addressed by list_rules, get_rule, create_new_rule tools and the rule://sg_rules/ resource.
• test cases: Mock test cases are provided as resources (e.g., testcase://python/example-test.py).
• supported langauges: Implemented by get_supported_languages() tool.
• support language kinds: Implemented by get_language_kinds() tool.
• dump code snippet ast: Implemented by dump_ast() tool.
• validate rule syntax: Implemented by validate_rule_syntax() tool.
• create new rule: Implemented by create_new_rule() tool.
• search codebase: Covered by existing find_code and find_code_by_rule tools.
• list all diagnostics in the workspace: Implemented by list_all_diagnostics_in_the_workspace() tool.

Not Directly Implemented / Out of Scope / Needs Clarification:

• utils global rules: "Global rules" are represented by a mock resource (rule://global/example-global-rule.yml). A system for managing actual, shareable global utility rules is not implemented.
• create new utils: No specific tool for creating "utils" was implemented as the definition of "utils" in this context is unclear (e.g., utility Python functions, new ast-grep rule utilities).
• get comprehensive llm txt: This is too vague. If it means getting text for an LLM to process, the existing tools and resources provide code, rules, and diagnostics that can be used for this. No specific tool named this was added.
• prompt: MCP prompts are a separate capability. While the server provides data that could be used in prompts, it doesn't define MCP prompt resources itself.
• simplify example: This is a high-level action, likely for an LLM to perform on code or rules, not a direct server tool.
• break down matching steps: This sounds like a debugging or explanatory feature for ast-grep's matching process, which is beyond the scope of an MCP server wrapping the CLI.
• combine steps: Similar to above, likely an LLM task for rule composition.
• verify matching output: The existing tools provide matching output. Verification would typically be done by the user or an LLM.
• get rule matching for text: The find_code and find_code_by_rule tools serve this purpose by finding matches in a project folder. A tool to match a rule against an ad-hoc text snippet (not in a project file) was not explicitly added but dump_ast followed by client-side rule application or a new tool could achieve this.

---

This refactoring makes the ast-grep-mcp server a more powerful and developer-friendly tool for integrating ast-grep's capabilities into LLM workflows via the Model Context Protocol.