Skip to content

Commit 74212cf

Browse files
tmaiarototmaiaroto
committed
add agent docs including prd and future plans to share with others
1 parent c16adab commit 74212cf

File tree

2 files changed

+257
-0
lines changed

2 files changed

+257
-0
lines changed

‎AGENT_DOCS/PLANS/SEMANTIC_ANALYSIS_PLAN.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Plan for Semantic Analysis Integration in MCP Server
2+
3+
## 1. Overview
4+
5+
This document outlines a phased approach to integrate semantic analysis into the `ast-grep-linter-mcp-server`. The goal is to evolve beyond purely syntactic pattern matching (`ast-grep`) and enable rules that can leverage type information and symbol resolution. This will dramatically increase the accuracy of our linting, reduce false positives, and allow for a much more powerful class of rules.
6+
7+
We will begin with Go, using the official Go language server (`gopls`), and then establish a framework for incorporating other languages over time.
8+
9+
---
10+
11+
## 2. Core Concept: The Hybrid Analysis Model
12+
13+
The server will operate in a hybrid mode, combining the speed of `ast-grep` for syntactic analysis with the precision of a language server for semantic validation.
14+
15+
The workflow for a semantic rule will be:
16+
1. **Syntactic Pre-filtering (`ast-grep`):** A broad `ast-grep` rule finds all potential candidates for a violation. For example, it finds all standalone function calls.
17+
2. **Semantic Verification (Language Server):** For each candidate found by `ast-grep`, the MCP server queries a language server (`gopls`) to get semantic information (e.g., "What are the return types of this function?").
18+
3. **Final Decision:** The server combines the syntactic and semantic information to make a final, accurate decision on whether to report a violation.
19+
20+
---
21+
22+
## 3. Phase 1: Go Language Support via `gopls`
23+
24+
### 3.1. Architecture
25+
26+
The MCP server will manage a long-running `gopls` process. It will communicate with `gopls` using the Language Server Protocol (LSP) over stdio.
27+
28+
### 3.2. New MCP Tools for Semantic Queries
29+
30+
We will introduce new tools to the MCP server that abstract the LSP communication.
31+
32+
#### Tool 1: `get_definition`
33+
- **Purpose:** Finds the definition of a symbol at a given position.
34+
- **Arguments:**
35+
- `file_path`: `string`
36+
- `line`: `int`
37+
- `column`: `int`
38+
- **Process:**
39+
1. Receives the request.
40+
2. Formats and sends a `textDocument/definition` request to the `gopls` process.
41+
3. Parses the `gopls` response, which contains the location (file and position) of the definition.
42+
4. Reads the source code at the definition's location to extract the full function signature or type definition.
43+
- **Returns:** A JSON object with the definition's `file_path`, `start_line`, `end_line`, and the full `signature` text.
44+
45+
#### Tool 2: `get_type_info`
46+
- **Purpose:** Gets type information for the symbol at a given position.
47+
- **Arguments:**
48+
- `file_path`: `string`
49+
- `line`: `int`
50+
- `column`: `int`
51+
- **Process:**
52+
1. Receives the request.
53+
2. Formats and sends a `textDocument/hover` request to `gopls`.
54+
3. Parses the `gopls` response to extract the type information string.
55+
- **Returns:** A JSON object containing the `type` as a string.
56+
57+
### 3.3. Enhanced `scan_code` Tool
58+
59+
The `scan_code` tool will be upgraded to support a new type of rule.
60+
61+
**New Rule Property: `semantic_check`**
62+
63+
Rules in `sgconfig.yml` can have an optional `semantic_check` property.
64+
65+
```yaml
66+
id: go-unchecked-error-semantic
67+
language: go
68+
rule:
69+
# 1. Syntactic pre-filter: find all standalone function calls
70+
pattern: $A($$$)
71+
inside:
72+
kind: expression_statement
73+
message: "The error returned by '$A' is not checked."
74+
severity: "error"
75+
# 2. Semantic verification step
76+
semantic_check:
77+
# The MCP server will execute this check
78+
- type: 'function_returns_error'
79+
# It will pass the matched node's info to the check
80+
input: '$A'
81+
```
82+
83+
**New `scan_code` Workflow:**
84+
1. Run `ast-grep` as usual.
85+
2. For each finding from a rule that has a `semantic_check`:
86+
a. Extract the AST node specified by `input` (e.g., `$A`).
87+
b. Get its position (file, line, column).
88+
c. Call the appropriate new MCP tool (`get_definition` or `get_type_info`).
89+
d. Analyze the returned signature/type to see if it matches the check (e.g., does it include `error` as a return type?).
90+
e. If the semantic check passes, the finding is confirmed and reported. If it fails, the finding is discarded as a false positive.
91+
92+
---
93+
94+
## 4. Phase 2: Framework for Multi-Language Support
95+
96+
### 4.1. Language Server Management
97+
98+
The MCP server will be updated to manage a pool of language server processes.
99+
- A configuration file (`language_servers.json`) will map language IDs (e.g., "go", "typescript", "python") to the command needed to start their respective language servers (e.g., `gopls`, `tsserver`, `pylance`).
100+
- The server will start and manage these processes on demand.
101+
102+
### 4.2. Generic Semantic Checks
103+
104+
The `semantic_check` types will be kept as generic as possible to be reusable across languages.
105+
- `function_returns_type`: Checks if a function returns a specific type name.
106+
- `variable_is_type`: Checks if a variable is of a certain type.
107+
- `is_deprecated`: Checks for deprecation annotations.
108+
109+
This creates a powerful, extensible system where adding support for a new language primarily involves adding its language server to the configuration and ensuring its output can be parsed.
110+
111+
---
112+
113+
## 5. Implementation Steps
114+
115+
1. **[Go]** Implement the `gopls` process management within the MCP server.
116+
2. **[Go]** Implement the `get_definition` tool by creating an LSP client that can send `textDocument/definition` requests.
117+
3. **[Go]** Update the `scan_code` handler to perform the hybrid analysis workflow described in section 3.3.
118+
4. **[Go]** Test the new `go-unchecked-error-semantic` rule.
119+
5. **[Framework]** Refactor the language server management to support multiple languages via a configuration file.
120+
6. **[Framework]** Generalize the semantic check logic.
121+
7. **[TypeScript]** Add `tsserver` to the configuration and implement a semantic rule for TypeScript as a proof of concept.

‎AGENT_DOCS/PRD/PRD.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# PRD & Technical Plan: context-sherpa - AI-Powered Code Analysis Server
2+
3+
**Version: 1.2**
4+
**Date: 2025-10-01**
5+
Author: Gemini
6+
7+
## 1. Overview
8+
9+
This document outlines the requirements for an MCP (Model-as-a-Tool Protocol) server, written in Go, that provides an AI coding agent with tools to interact with `ast-grep`. The primary objective is to create a system where an AI agent can not only lint and validate code using a predefined set of rules but also dynamically create, update, and remove those rules based on natural language feedback from a developer.
10+
11+
The final product will be a single, portable, cross-platform binary with no external runtime dependencies, making setup trivial for the end-user.
12+
13+
## 2. Core Objective & User Story
14+
15+
As a developer using an AI coding agent, I want to:
16+
17+
- Have my agent automatically validate the code it generates against my project's specific coding patterns.
18+
- Be able to provide natural language feedback (e.g., "From now on, all async functions must have a try/catch block") to my agent.
19+
- Have the agent intelligently convert my feedback into a permanent, machine-readable linting rule using `ast-grep`.
20+
- Be able to easily remove rules that are no longer needed.
21+
- Ensure this system is self-contained in a single executable that I can easily run without managing servers, dependencies, or security risks.
22+
23+
## 3. Key Features & Tool Definitions for the AI Agent
24+
25+
The MCP server will expose the following **four** tools to the AI agent. The agent will use the tool descriptions to decide which tool to call based on the user's request.
26+
27+
### Tool 1: `initialize_ast_grep`
28+
29+
- **Description**: "Initializes an ast-grep project if one is not already present. It creates the `sgconfig.yml` file and a `rules` directory. This tool should be suggested if another tool fails due to a missing configuration file."
30+
- **Input Schema**: (None)
31+
- **Output Schema**:
32+
- `success` (boolean): `true` if the project was initialized successfully.
33+
- `message` (string): A confirmation message (e.g., "ast-grep project initialized successfully. Created sgconfig.yml and rules/ directory.").
34+
35+
### Tool 2: `scan_code`
36+
37+
- **Description**: "Scans a given code snippet using the project's central `ast-grep` ruleset (`sgconfig.yml`). Use this to validate code, check for rule violations, or before committing changes."
38+
- **Input Schema**:
39+
- `code` (string, required): The raw source code to scan.
40+
- `language` (string, required): The programming language of the code (e.g., `javascript`, `python`, `go`).
41+
- **Output Schema**:
42+
- `success` (boolean): `true` if no issues were found, `false` otherwise.
43+
- `issues` (array of objects): A list of violations found. Each object contains:
44+
- `ruleId` (string): The ID of the rule that was violated.
45+
- `message` (string): The error message for the violation.
46+
- `line` (integer): The line number where the violation occurred.
47+
48+
### Tool 3: `add_or_update_rule`
49+
50+
- **Description**: "Adds a new rule or updates an existing rule in the project's central `sgconfig.yml` file. Use this after a rule has been generated and confirmed by the user."
51+
- **Input Schema**:
52+
- `rule_id` (string, required): A unique identifier for the rule (e.g., `no-console-log`).
53+
- `rule_yaml` (string, required): The complete YAML definition for the rule.
54+
- **Output Schema**:
55+
- `success` (boolean): `true` if the file was written successfully.
56+
- `message` (string): A confirmation message (e.g., "Rule 'no-console-log' was added successfully.").
57+
58+
### Tool 4: `remove_rule`
59+
60+
- **Description**: "Removes a rule from the project's central `sgconfig.yml` file by its unique ID. Use this when a coding standard is no longer desired."
61+
- **Input Schema**:
62+
- `rule_id` (string, required): The unique identifier of the rule to remove.
63+
- **Output Schema**:
64+
- `success` (boolean): `true` if the rule was found and removed successfully.
65+
- `message` (string): A confirmation message (e.g., "Rule 'no-console-log' was removed successfully.").
66+
67+
## 4. Technical Implementation Plan
68+
69+
This plan details the steps to build the server using Go, embedding the `ast-grep` binary directly.
70+
71+
### Step A: Project Setup
72+
(No changes)
73+
74+
### Step B: Bundle the ast-grep Binary
75+
(No changes)
76+
77+
### Step C: Implement the MCP Server
78+
79+
- In `main()`, create a new MCP server instance.
80+
- Register a handler for each of the three tools defined above.
81+
- `server.RegisterTool("scan_code", scanCodeHandler)`
82+
- `server.RegisterTool("add_or_update_rule", addOrUpdateRuleHandler)`
83+
- `server.RegisterTool("remove_rule", removeRuleHandler)`
84+
- Start the server to listen for requests from the AI agent.
85+
86+
### Step D: Implement Tool Handler Functions
87+
88+
- `scanCodeHandler(req mcp.Request) mcp.Response`: (No changes)
89+
- `addOrUpdateRuleHandler(req mcp.Request) mcp.Response`: (No changes)
90+
- `removeRuleHandler(req mcp.Request) mcp.Response`: (No changes)
91+
92+
## 5. Non-Functional Requirements
93+
(No changes)
94+
95+
## 6. Testing Strategy & Usage Example
96+
97+
### Testing
98+
99+
- **Unit Tests**: Each handler function (`scanCodeHandler`, `addOrUpdateRuleHandler`, etc.) will have corresponding unit tests. External dependencies will be mocked.
100+
- **Integration Tests**: An end-to-end test script will be created to compile the binary, start it, and simulate an MCP client making a sequence of calls to add, scan, and remove rules, verifying the `sgconfig.yml` content at each stage.
101+
102+
### Example Usage Workflow
103+
104+
This scenario illustrates the updated interaction between a developer, the AI agent, and the MCP server.
105+
106+
1. **Agent handles a missing configuration file:**
107+
- **Developer**: "Hey agent, please add a rule to disallow `fmt.Println` in our Go code."
108+
- **AI Agent**: Calls the `add_or_update_rule` tool.
109+
- **MCP Server**: Fails because `sgconfig.yml` does not exist and returns an error: "Error: sgconfig.yml not found. Please run the 'initialize_ast_grep' tool first to set up the project."
110+
- **AI Agent**: "It looks like this project hasn't been set up for ast-grep yet. Would you like me to initialize it for you?"
111+
- **Developer**: "Yes, please."
112+
- **AI Agent**: Calls the `initialize_ast_grep` tool.
113+
- **MCP Server**: Creates `sgconfig.yml` and the `rules/` directory.
114+
- **AI Agent**: "The project has been initialized. I will now add the rule."
115+
- **AI Agent**: Calls `add_or_update_rule` again, which now succeeds.
116+
117+
2. **Developer sets a new rule:**
118+
- **Developer**: "Hey agent, we should never use the `eval()` function in our JavaScript. It's a security risk. Can you create a rule to block it?"
119+
- **AI Agent**: Understands the intent. It uses its internal knowledge to generate a valid `ast-grep` YAML rule.
120+
- **AI Agent**: "I've drafted this rule: [shows YAML to user]. Does this look correct?"
121+
- **Developer**: "Yes, that's perfect."
122+
- **AI Agent**: Calls the `add_or_update_rule` tool with the YAML to save it to `sgconfig.yml`.
123+
124+
2. **Agent self-corrects its own code:**
125+
- **Developer**: "Now, please refactor this old utility file to be more modern."
126+
- **AI Agent**: Generates a refactored version of the code, mistakenly using `eval()`.
127+
- **Agent (Internal Step)**: Before showing the code, it calls the `scan_code` tool on its own output.
128+
- **MCP Server**: Runs `ast-grep scan`, finds the `eval()` call, and returns a violation.
129+
- **AI Agent**: Sees the violation, corrects its code to use a safer alternative, and re-scans to confirm compliance.
130+
- **AI Agent**: "Here is the refactored code. I've also updated a part that was using `eval()` to be more secure."
131+
132+
3. **Developer removes a rule:**
133+
- **Developer**: "You know what, the `no-console-log` rule is too annoying for our debug builds. Please remove it."
134+
- **AI Agent**: Calls the `remove_rule` tool with `rule_id: "no-console-log"`.
135+
- **MCP Server**: Removes the rule from `sgconfig.yml`.
136+
- **AI Agent**: "Done. The `no-console-log` rule has been removed."

0 commit comments

Comments
 (0)