🔧 Make repository parameter required in MCP tools

Enforce explicit repository path specification for MCP tools

This change improves reliability when Git-Iris is used through MCP clients:

- Add repository parameter validation across all MCP tools
- Update parameter description from optional to required
- Remove fallback to default repo in resolve_git_repo
- Add validation to ensure local paths exist and are git repos
- Update documentation with examples for both local and remote repos
- Add explanation of why repository parameter is required

This addresses reliability issues with clients like Cursor that don't
provide consistent project path information.

Author: hyperb1iss

README.md

@@ -281,6 +281,34 @@ git-iris serve --transport sse --port 3077
 
 This allows you to use Git-Iris features directly from Claude, Cursor, VSCode, and other MCP-compatible tools. See [MCP.md](docs/MCP.md) for detailed documentation.
 
+#### MCP Tool Parameters
+
+All MCP tools **require** the `repository` parameter, which must be a local project path or a remote repository URL. This is necessary because some clients (like Cursor) do not reliably provide the project root.
+
+**Example (local path):**
+```json
+{
+  "from": "v1.0.0",
+  "to": "v2.0.0",
+  "detail_level": "detailed",
+  "repository": "/home/bliss/dev/myproject"
+}
+```
+
+**Example (remote URL):**
+```json
+{
+  "from": "v1.0.0",
+  "to": "v2.0.0",
+  "detail_level": "detailed",
+  "repository": "https://github.com/example/repo.git"
+}
+```
+
+**Why is `repository` required?**
+
+> Due to limitations in some MCP clients, the server cannot reliably infer the project root or repository path. To ensure Git-Iris always operates on the correct repository, you must explicitly specify the `repository` parameter for every tool call. This eliminates ambiguity and ensures your commands are always precise and predictable.
+
 ### Interactive Commit Process
 
 The interactive CLI allows you to refine and perfect your commit messages:

docs/MCP.md

@@ -43,16 +43,29 @@ Generate commit messages and perform Git commits.
 - `no_verify`: (boolean) Skip verification for commit action
 - `preset`: (string) Instruction preset to use
 - `custom_instructions`: (string) Custom instructions for the AI
-- `repository`: (string, optional) Repository path or URL
+- `repository`: (string, required) Repository path (local) or URL (remote). **Required.**
 
-Example:
+Example (local path):
 
 ```json
 {
   "auto_commit": true,
   "use_gitmoji": true,
   "preset": "conventional",
-  "custom_instructions": "Include the ticket number from JIRA"
+  "custom_instructions": "Include the ticket number from JIRA",
+  "repository": "/home/bliss/dev/myproject"
+}
+```
+
+Example (remote URL):
+
+```json
+{
+  "auto_commit": true,
+  "use_gitmoji": true,
+  "preset": "conventional",
+  "custom_instructions": "Include the ticket number from JIRA",
+  "repository": "https://github.com/example/repo.git"
 }
 ```
 
@@ -66,15 +79,27 @@ Generate comprehensive code reviews with options for staged changes, unstaged ch
 - `commit_id`: (string) Specific commit to review (hash, branch name, or reference)
 - `preset`: (string) Preset instruction set to use for the review
 - `custom_instructions`: (string) Custom instructions for the AI
-- `repository`: (string, optional) Repository path or URL
+- `repository`: (string, required) Repository path (local) or URL (remote). **Required.**
 
-Example:
+Example (local path):
 
 ```json
 {
   "preset": "security",
   "custom_instructions": "Focus on performance issues",
-  "include_unstaged": true
+  "include_unstaged": true,
+  "repository": "/home/bliss/dev/myproject"
+}
+```
+
+Example (remote URL):
+
+```json
+{
+  "preset": "security",
+  "custom_instructions": "Focus on performance issues",
+  "include_unstaged": true,
+  "repository": "https://github.com/example/repo.git"
 }
 ```
 
@@ -88,16 +113,29 @@ Generate a detailed changelog between two Git references.
 - `to`: (string) Ending reference (defaults to HEAD if not specified)
 - `detail_level`: (string) Level of detail for the changelog (minimal, standard, detailed)
 - `custom_instructions`: (string) Custom instructions for the AI
-- `repository`: (string, optional) Repository path or URL
+- `repository`: (string, required) Repository path (local) or URL (remote). **Required.**
 
-Example:
+Example (local path):
 
 ```json
 {
   "from": "v1.0.0",
   "to": "v2.0.0",
   "detail_level": "detailed",
-  "custom_instructions": "Group changes by component"
+  "custom_instructions": "Group changes by component",
+  "repository": "/home/bliss/dev/myproject"
+}
+```
+
+Example (remote URL):
+
+```json
+{
+  "from": "v1.0.0",
+  "to": "v2.0.0",
+  "detail_level": "detailed",
+  "custom_instructions": "Group changes by component",
+  "repository": "https://github.com/example/repo.git"
 }
 ```
 
@@ -111,19 +149,36 @@ Generate comprehensive release notes between two Git references.
 - `to`: (string) Ending reference (defaults to HEAD if not specified)
 - `detail_level`: (string) Level of detail for the release notes (minimal, standard, detailed)
 - `custom_instructions`: (string) Custom instructions for the AI
-- `repository`: (string, optional) Repository path or URL
+- `repository`: (string, required) Repository path (local) or URL (remote). **Required.**
+
+Example (local path):
+
+```json
+{
+  "from": "v1.0.0",
+  "to": "v2.0.0",
+  "detail_level": "standard",
+  "custom_instructions": "Highlight breaking changes",
+  "repository": "/home/bliss/dev/myproject"
+}
+```
 
-Example:
+Example (remote URL):
 
 ```json
 {
   "from": "v1.0.0",
   "to": "v2.0.0",
   "detail_level": "standard",
-  "custom_instructions": "Highlight breaking changes"
+  "custom_instructions": "Highlight breaking changes",
+  "repository": "https://github.com/example/repo.git"
 }
 ```
 
+## Why is `repository` required?
+
+Due to limitations in some MCP clients (such as Cursor and others), the server cannot reliably infer the project root or repository path. To ensure Git-Iris always operates on the correct repository, you must explicitly specify the `repository` parameter for every tool call. This can be either a local filesystem path (for local projects) or a remote repository URL (for remote operations). This eliminates ambiguity and ensures your commands are always precise and predictable.
+
 ## Using Git-Iris with Claude
 
 ### Claude Desktop Integration

src/mcp/tools/changelog.rs

@@ -8,7 +8,7 @@ use crate::git::GitRepo;
 use crate::log_debug;
 use crate::mcp::tools::utils::{
     GitIrisTool, apply_custom_instructions, create_text_result, parse_detail_level,
-    resolve_git_repo,
+    resolve_git_repo, validate_repository_parameter,
 };
 
 use rmcp::handler::server::tool::cached_schema_for_type;
@@ -37,8 +37,7 @@ pub struct ChangelogTool {
     #[serde(default)]
     pub custom_instructions: String,
 
-    /// Repository path or URL (optional)
-    #[serde(default)]
+    /// Repository path (local) or URL (remote). Required.
     pub repository: String,
 }
 
@@ -66,13 +65,9 @@ impl GitIrisTool for ChangelogTool {
     ) -> Result<CallToolResult, anyhow::Error> {
         log_debug!("Generating changelog with: {:?}", self);
 
-        // Resolve repository based on the repository parameter
-        let repo_path = if self.repository.trim().is_empty() {
-            None
-        } else {
-            Some(self.repository.as_str())
-        };
-        let git_repo = resolve_git_repo(repo_path, git_repo)?;
+        // Validate repository parameter
+        validate_repository_parameter(&self.repository)?;
+        let git_repo = resolve_git_repo(Some(self.repository.as_str()), git_repo)?;
         log_debug!("Using repository: {}", git_repo.repo_path().display());
 
         // Parse detail level using shared utility

src/mcp/tools/codereview.rs

@@ -9,6 +9,7 @@ use crate::git::GitRepo;
 use crate::log_debug;
 use crate::mcp::tools::utils::{
     GitIrisTool, apply_custom_instructions, create_text_result, resolve_git_repo,
+    validate_repository_parameter,
 };
 
 use rmcp::handler::server::tool::cached_schema_for_type;
@@ -38,8 +39,7 @@ pub struct CodeReviewTool {
     #[serde(default)]
     pub custom_instructions: String,
 
-    /// Repository path or URL (optional)
-    #[serde(default)]
+    /// Repository path (local) or URL (remote). Required.
     pub repository: String,
 }
 
@@ -67,13 +67,9 @@ impl GitIrisTool for CodeReviewTool {
     ) -> Result<CallToolResult, anyhow::Error> {
         log_debug!("Generating code review with: {:?}", self);
 
-        // Resolve repository based on the repository parameter
-        let repo_path = if self.repository.trim().is_empty() {
-            None
-        } else {
-            Some(self.repository.as_str())
-        };
-        let git_repo = resolve_git_repo(repo_path, git_repo)?;
+        // Validate repository parameter
+        validate_repository_parameter(&self.repository)?;
+        let git_repo = resolve_git_repo(Some(self.repository.as_str()), git_repo)?;
         log_debug!("Using repository: {}", git_repo.repo_path().display());
 
         // Check if local operations are required without a specific commit

src/mcp/tools/commit.rs

@@ -7,7 +7,9 @@ use crate::commit::types::format_commit_message;
 use crate::config::Config as GitIrisConfig;
 use crate::git::GitRepo;
 use crate::log_debug;
-use crate::mcp::tools::utils::{GitIrisTool, create_text_result, resolve_git_repo};
+use crate::mcp::tools::utils::{
+    GitIrisTool, create_text_result, resolve_git_repo, validate_repository_parameter,
+};
 
 use rmcp::handler::server::tool::cached_schema_for_type;
 use rmcp::model::{CallToolResult, Tool};
@@ -40,8 +42,7 @@ pub struct CommitTool {
     #[serde(default)]
     pub custom_instructions: String,
 
-    /// Repository path or URL (optional)
-    #[serde(default)]
+    /// Repository path (local) or URL (remote). Required.
     pub repository: String,
 }
 
@@ -69,13 +70,9 @@ impl GitIrisTool for CommitTool {
     ) -> Result<CallToolResult, anyhow::Error> {
         log_debug!("Processing commit request with: {:?}", self);
 
-        // Resolve repository based on the repository parameter
-        let repo_path = if self.repository.trim().is_empty() {
-            None
-        } else {
-            Some(self.repository.as_str())
-        };
-        let git_repo = resolve_git_repo(repo_path, git_repo)?;
+        // Validate repository parameter
+        validate_repository_parameter(&self.repository)?;
+        let git_repo = resolve_git_repo(Some(self.repository.as_str()), git_repo)?;
         log_debug!("Using repository: {}", git_repo.repo_path().display());
 
         // Check if we can perform the operation on this repository

src/mcp/tools/releasenotes.rs

@@ -8,7 +8,7 @@ use crate::git::GitRepo;
 use crate::log_debug;
 use crate::mcp::tools::utils::{
     GitIrisTool, apply_custom_instructions, create_text_result, parse_detail_level,
-    resolve_git_repo,
+    resolve_git_repo, validate_repository_parameter,
 };
 
 use rmcp::handler::server::tool::cached_schema_for_type;
@@ -37,8 +37,7 @@ pub struct ReleaseNotesTool {
     #[serde(default)]
     pub custom_instructions: String,
 
-    /// Repository path or URL (optional)
-    #[serde(default)]
+    /// Repository path (local) or URL (remote). Required.
     pub repository: String,
 }
 
@@ -66,13 +65,9 @@ impl GitIrisTool for ReleaseNotesTool {
     ) -> Result<CallToolResult, anyhow::Error> {
         log_debug!("Generating release notes with: {:?}", self);
 
-        // Resolve repository based on the repository parameter
-        let repo_path = if self.repository.trim().is_empty() {
-            None
-        } else {
-            Some(self.repository.as_str())
-        };
-        let git_repo = resolve_git_repo(repo_path, git_repo)?;
+        // Validate repository parameter
+        validate_repository_parameter(&self.repository)?;
+        let git_repo = resolve_git_repo(Some(self.repository.as_str()), git_repo)?;
         log_debug!("Using repository: {}", git_repo.repo_path().display());
 
         // Parse detail level using shared utility

src/mcp/tools/utils.rs

@@ -6,7 +6,6 @@ use crate::common::DetailLevel;
 use crate::config::Config as GitIrisConfig;
 use crate::git::GitRepo;
 use rmcp::model::{Annotated, CallToolResult, Content, RawContent, RawTextContent};
-use std::path::Path;
 use std::sync::Arc;
 
 /// Common trait for all Git-Iris MCP tools
@@ -57,13 +56,38 @@ pub fn apply_custom_instructions(config: &mut crate::config::Config, custom_inst
     }
 }
 
-/// Resolves a Git repository from an optional `repo_path` parameter
+/// Validates the repository parameter: must be non-empty, and if local, must exist and be a git repo
+pub fn validate_repository_parameter(repo: &str) -> Result<(), anyhow::Error> {
+    if repo.trim().is_empty() {
+        return Err(anyhow::anyhow!(
+            "The `repository` parameter is required and must be a valid local path or remote URL."
+        ));
+    }
+    if !(repo.starts_with("http://") || repo.starts_with("https://") || repo.starts_with("git@")) {
+        let path = std::path::Path::new(repo);
+        if !path.exists() {
+            return Err(anyhow::anyhow!(format!(
+                "The specified repository path does not exist: {}",
+                repo
+            )));
+        }
+        if !path.join(".git").exists() {
+            return Err(anyhow::anyhow!(format!(
+                "The specified path is not a git repository: {}",
+                repo
+            )));
+        }
+    }
+    Ok(())
+}
+
+/// Resolves a Git repository from a `repo_path` parameter
 ///
 /// If `repo_path` is provided, creates a new `GitRepo` for that path/URL.
-/// Otherwise, falls back to the default `git_repo` provided by the handler.
+/// Assumes the parameter has already been validated.
 pub fn resolve_git_repo(
     repo_path: Option<&str>,
-    default_git_repo: Arc<GitRepo>,
+    _default_git_repo: Arc<GitRepo>,
 ) -> Result<Arc<GitRepo>, anyhow::Error> {
     match repo_path {
         Some(path) if !path.trim().is_empty() => {
@@ -75,10 +99,12 @@ pub fn resolve_git_repo(
                 Ok(Arc::new(GitRepo::new_from_url(Some(path.to_string()))?))
             } else {
                 // Handle local repository path
-                let path = Path::new(path);
+                let path = std::path::Path::new(path);
                 Ok(Arc::new(GitRepo::new(path)?))
             }
         }
-        _ => Ok(default_git_repo),
+        _ => Err(anyhow::anyhow!(
+            "The `repository` parameter is required and must be a valid local path or remote URL."
+        )),
     }
 }