feat: add find_project, remove_test_cases_from_launch, and initialize instructions

- find_project: resolve a project by name/code (e.g. "TSi") to its numeric ID
  via a client-side scan of /api/project (no server-side name filter exists).
- remove_test_cases_from_launch: trim test cases from a launch by hiding
  (default, non-destructive) or permanently deleting their test results.
- initialize now returns an `instructions` capability overview so MCP clients
  tell the model what the server can do, improving tool discoverability.

Tool count 112 -> 114. Docs (README, RELEASES, API.md, llms.txt, llms-full.txt,
CHANGELOG) synced; validation tests and an initialize-instructions test added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: MimoJanra

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-06-19 - Project Search, Launch Cleanup & Tool Discoverability
+
+### Added
+
+- **`find_project`** — find a project by name or code (case-insensitive substring match). Resolves a human-readable name/code (e.g. `TSi`) to its numeric project ID without paging through `list_projects` or guessing IDs. Scans `/api/project` client-side since the Allure TestOps API exposes no server-side project name filter; returns `matches`, `count`, `scanned`, and a `truncated` flag when more matches may exist beyond `limit` (default 20) or the 5000-project scan cap.
+
+- **`remove_test_cases_from_launch`** — remove test cases from a launch (e.g. to trim a launch with too many cases or duplicates, including already-started ones). Resolves each `test_case_id` to its test result(s) in the launch — including retries — and removes them. `mode="hide"` (default) excludes the results from the report but keeps the data (`POST /api/testresult/bulk/hide`, non-destructive); `mode="delete"` permanently deletes them (`DELETE /api/testresult/{id}`). Since the Allure API has no bulk test-result delete, `delete` issues one request per result and reports per-result failures under `failed`. Returns `removed_count`, `removed_result_ids`, `not_found_test_case_ids`, and `truncated`.
+
+- **`initialize` now returns an `instructions` field** — the MCP handshake response includes a capability overview (tool groups, how to resolve names→IDs, the `search_testops_operations`/`execute_testops_operation` fallback for the 600+ endpoints, and safety notes). MCP clients add this to the model's system prompt, so Claude knows what the server can do instead of inferring it from bare tool names. Directly improves tool discoverability.
+
+- Tool count: 112 → 114.
+
+### Fixed
+
+- **`llms.txt` listed the removed `update_launch_environment` tool** — dropped from the Launches group (it was removed in 2.0.3) and the group count corrected.
+
 ## [2.0.3] - 2026-06-01 - API Compliance Fixes
 
 ### Fixed

README.md

@@ -26,7 +26,7 @@ Integrate **Allure TestOps** with Claude using the Model Context Protocol. Launc
 - Works with Claude Desktop, Claude Web, and custom MCP clients
 
 ### 🏭 Production-Grade
-- **112 tools** — complete Allure TestOps test case API coverage + full OpenAPI fallback (600+ endpoints)
+- **114 tools** — complete Allure TestOps test case API coverage + full OpenAPI fallback (600+ endpoints)
 - **MCP Prompts** — built-in templates (`analyze-test-failures`, `launch-report-summary`) for one-click workflows
 - **MCP Resources** — attach `allure://docs/quickstart` as context; widget resources for visual dashboards
 - **AI analysis** — `analyze_launch_failures` asks Claude to find root causes via MCP sampling
@@ -324,7 +324,7 @@ If you prefer running without Docker:
 - **`configure_allure_token`** — Set token in chat (if not in config)
 
 ### Launch Management
-`run_allure_launch`\* • `get_launch_status` • `get_launch_report` • `list_launches` • `get_launch_details` • `close_launch` • `reopen_launch` • `copy_launch`\* • `merge_launches`\* • `get_launch_environment` • `update_launch_environment`
+`run_allure_launch`\* • `get_launch_status` • `get_launch_report` • `list_launches` • `get_launch_details` • `close_launch` • `reopen_launch` • `copy_launch`\* • `merge_launches`\* • `get_launch_environment` • `add_test_cases_to_launch` • `add_test_plan_to_launch` • `remove_test_cases_from_launch`
 
 > \* async — returns `task_id` immediately; track with `get_task_status`
 
@@ -359,7 +359,7 @@ If you prefer running without Docker:
 `bulk_set_test_case_status` • `bulk_add_test_case_tags` • `bulk_remove_test_case_tags` • `bulk_clone_test_cases` • `bulk_mute_test_cases` • `bulk_delete_test_cases` • `bulk_move_test_cases` • `bulk_set_test_case_layer` • `bulk_add_test_case_members` • `bulk_remove_test_case_members` • `bulk_add_test_case_custom_fields` • `bulk_remove_test_case_custom_fields` • `bulk_add_test_case_external_links` • `bulk_add_test_case_issues` • `bulk_remove_test_case_issues` • `bulk_run_test_cases_new_launch` • `bulk_run_test_cases_existing_launch` • `bulk_create_test_plan`
 
 ### Projects & Analytics
-`list_projects` • `get_project` • `get_project_stats` • `get_launch_trend_analytics` • `get_launch_duration_analytics` • `get_test_success_rate`
+`list_projects` • `find_project` • `get_project` • `get_project_stats` • `get_launch_trend_analytics` • `get_launch_duration_analytics` • `get_test_success_rate`
 
 ### Async Task Management
 `get_task_status` • `list_running_tasks` • `cancel_task`

RELEASES.md

@@ -5,7 +5,7 @@ All pre-built binaries are provided for easy setup without requiring Go installa
 ## 🆕 What's New in v2.0.0
 
 - **MCP protocol 2025-11-25** with version negotiation and stable cursor-based pagination
-- **112 tools** (+ `get_task_status`, `list_running_tasks`, `cancel_task`, `analyze_launch_failures`)
+- **114 tools** (+ `find_project`, `remove_test_cases_from_launch`, `get_task_status`, `list_running_tasks`, `cancel_task`, `analyze_launch_failures`)
 - **Async task system** — `run_allure_launch`, `copy_launch`, `merge_launches`, bulk runs return `task_id` immediately; tasks auto-expire after 1 hour
 - **AI failure analysis** — `analyze_launch_failures` asks Claude to identify root causes via MCP sampling
 - **Confirmation dialogs** — `delete_test_case` / `bulk_delete_test_cases` require user confirmation via elicitation (requires HTTP transport; stdio returns an error)
@@ -185,7 +185,7 @@ xattr -d com.apple.quarantine ./testops-darwin-amd64
 
 ## 📚 Available Tools
 
-Over **112 MCP tools** for Allure TestOps integration:
+Over **114 MCP tools** for Allure TestOps integration:
 
 - Launch management (create, run\*, close, reopen, copy\*, merge\*) — \*async
 - Test case operations (create, update, delete†, clone, restore, versions, audit) — †with confirmation

docs/API.md

@@ -235,9 +235,25 @@ Add a test plan to a launch.
 
 ---
 
+### 10. `remove_test_cases_from_launch`
+
+Remove test cases from a launch. Resolves each `test_case_id` to its test result(s) in the launch (including retries) and removes them — use to trim a launch that has too many cases or duplicates.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `launch_id` | integer | ✓ | Launch ID to remove test cases from |
+| `test_case_ids` | integer[] | ✓ | Test case IDs to remove |
+| `mode` | string | | `hide` (default) excludes results from the report but keeps the data; `delete` permanently deletes them |
+
+Returns `removed_count`, `removed_result_ids`, `not_found_test_case_ids`, and `truncated`. In `delete` mode, any per-result failures are listed under `failed`. No bulk-delete API exists, so `delete` issues one `DELETE` per result.
+
+---
+
 ## Test Results Management Tools
 
-### 10. `list_test_results`
+### 11. `list_test_results`
 
 List test results in a launch with optional status filter.
 
@@ -252,7 +268,7 @@ List test results in a launch with optional status filter.
 
 ---
 
-### 11. `get_test_result`
+### 12. `get_test_result`
 
 Get detailed information about a single test result.
 
@@ -264,7 +280,7 @@ Get detailed information about a single test result.
 
 ---
 
-### 12. `assign_test_result`
+### 13. `assign_test_result`
 
 Assign a test result to a team member.
 
@@ -277,7 +293,7 @@ Assign a test result to a team member.
 
 ---
 
-### 13. `mute_test_result`
+### 14. `mute_test_result`
 
 Mute a failing test result (mark as known issue).
 
@@ -405,7 +421,22 @@ List all accessible projects.
 
 ---
 
-### 28. `get_project`
+### 28. `find_project`
+
+Find a project by name or code (case-insensitive substring match). Resolves a human-readable name/code (e.g. `TSi`) to its numeric project ID — instead of paging through `list_projects` or guessing IDs.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | ✓ | Name or code to match (case-insensitive substring) |
+| `limit` | integer | | Max matches to return (1–100, default 20) |
+
+Returns `matches` (array of `{id, name, code}`), `count`, `scanned`, and `truncated` (`true` if more matches may exist beyond `limit` or the scan cap).
+
+---
+
+### 29. `get_project`
 
 Get project details and settings.
 
@@ -417,7 +448,7 @@ Get project details and settings.
 
 ---
 
-### 29. `get_project_stats`
+### 30. `get_project_stats`
 
 Get project statistics (test count, runs, automation %).
 
@@ -429,7 +460,7 @@ Get project statistics (test count, runs, automation %).
 
 ---
 
-### 30. `get_launch_trend_analytics`
+### 31. `get_launch_trend_analytics`
 
 Get launch trend data over time (passed/failed/broken/skipped).
 
@@ -441,7 +472,7 @@ Get launch trend data over time (passed/failed/broken/skipped).
 
 ---
 
-### 31. `get_launch_duration_analytics`
+### 32. `get_launch_duration_analytics`
 
 Get launch execution time distribution.
 
@@ -453,7 +484,7 @@ Get launch execution time distribution.
 
 ---
 
-### 32. `get_test_success_rate`
+### 33. `get_test_success_rate`
 
 Get test case success rate metrics.
 

internal/adapters/allure/client.go

@@ -2108,6 +2108,64 @@ func (c *Client) BulkAssignTestResults(ctx context.Context, launchID int64, test
 	return nil
 }
 
+// DeleteTestResult permanently deletes a single test result by ID, removing it
+// (and the test case it represents) from the launch it belongs to.
+func (c *Client) DeleteTestResult(ctx context.Context, testResultID int64) error {
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodDelete, c.url(fmt.Sprintf("/api/testresult/%d", testResultID)), nil)
+	if err != nil {
+		return fmt.Errorf("create request: %w", err)
+	}
+	if err := c.setAuthHeader(ctx, httpReq); err != nil {
+		return fmt.Errorf("set auth: %w", err)
+	}
+
+	resp, err := c.httpClient.Do(httpReq)
+	if err != nil {
+		return fmt.Errorf("http request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNoContent {
+		return errFromResponse(resp)
+	}
+	return nil
+}
+
+// BulkHideTestResults hides the given test results in a launch
+// (POST /api/testresult/bulk/hide). Hidden results stay in the launch data but
+// are excluded from the report; unlike DeleteTestResult this is non-destructive.
+func (c *Client) BulkHideTestResults(ctx context.Context, launchID int64, testResultIDs []int64) error {
+	body, err := json.Marshal(TestResultBulkDto{
+		Selection: TestResultTreeSelectionDto{
+			LaunchID:     launchID,
+			LeafsInclude: testResultIDs,
+		},
+	})
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url("/api/testresult/bulk/hide"), bytes.NewBuffer(body))
+	if err != nil {
+		return fmt.Errorf("create request: %w", err)
+	}
+	if err := c.setAuthHeader(ctx, httpReq); err != nil {
+		return fmt.Errorf("set auth: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.httpClient.Do(httpReq)
+	if err != nil {
+		return fmt.Errorf("http request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
+		return errFromResponse(resp)
+	}
+	return nil
+}
+
 func (c *Client) BulkMuteTestResults(ctx context.Context, launchID int64, testResultIDs []int64, reason string) error {
 	selection := TestResultTreeSelectionDto{
 		LaunchID:     launchID,

internal/adapters/allure/models.go

@@ -685,6 +685,12 @@ type TestResultBulkResolveDto struct {
 	Issues    []interface{}              `json:"issues,omitempty"`
 }
 
+// TestResultBulkDto is the request body for selection-only bulk test result
+// operations such as POST /api/testresult/bulk/hide.
+type TestResultBulkDto struct {
+	Selection TestResultTreeSelectionDto `json:"selection"`
+}
+
 // ── Launch population DTOs ────────────────────────────────────────────────────
 
 type LaunchTestCasesAddDto struct {

internal/mcp/protocol.go

@@ -79,6 +79,10 @@ type InitializeResponse struct {
 		Name    string `json:"name"`
 		Version string `json:"version"`
 	} `json:"serverInfo"`
+	// Instructions is an optional overview of the server's capabilities that
+	// MCP clients add to the model's system prompt, so the model knows what
+	// tools/workflows exist without having to infer them from tool names alone.
+	Instructions string `json:"instructions,omitempty"`
 }
 
 // PaginatedRequest and PaginatedResponse support cursor-based pagination

internal/mcp/server.go

@@ -359,6 +359,31 @@ func (s *Server) handleJSONRPCResponse(ctx context.Context, req *JSONRPCRequest)
 	}
 }
 
+// serverInstructions is returned in the initialize response so MCP clients can
+// surface an overview of this server's capabilities to the model. It is meant
+// to answer "what can I do here, and how do I find it" up front, so the model
+// does not have to guess from bare tool names.
+const serverInstructions = `Allure TestOps integration for test management. You have 100+ dedicated tools plus a search/execute fallback that covers 600+ API endpoints — if you don't see a dedicated tool, assume the capability still exists and find it before giving up.
+
+Tool groups:
+- Launches: run_allure_launch, list_launches, get_launch_status/details/report, close/reopen/copy/merge_launch, add_test_cases_to_launch, add_test_plan_to_launch, remove_test_cases_from_launch.
+- Test results: list_test_results, get_test_result, assign/mute/resolve/unmute_test_result, plus bulk_* variants.
+- Test cases: list/get/create/update/delete/clone/restore, steps & scenario, tags/issues/links/members/custom-fields/relations, versions, attachments, search_test_cases, suggest_test_cases.
+- Folder tree: browse_test_case_tree, get_test_case_tree_folders, move_test_cases_to_folder, create_test_case_folder.
+- Bulk test-case ops: bulk_set/add/remove/move/run/delete_* (act on many cases at once).
+- Projects: list_projects, find_project (resolve a name or code like "TSi" to its numeric ID), get_project, get_project_stats.
+- Analytics: get_launch_trend_analytics, get_launch_duration_analytics, get_test_success_rate.
+- Async tasks: long operations return a task_id immediately — poll get_task_status, see list_running_tasks, cancel_task.
+- AI: analyze_launch_failures.
+
+Finding things:
+- Most tools take numeric IDs. To turn a human name/code into an ID: find_project (projects), list_launches (launches in a project), list_test_cases or search_test_cases (cases).
+- For anything without a dedicated tool, call search_testops_operations with your intent, then execute_testops_operation to run the operation it returns.
+
+Safety:
+- Destructive tools (delete_*, bulk_delete_*, and remove_test_cases_from_launch with mode=delete) permanently remove data — confirm intent first and prefer non-destructive options (e.g. remove_test_cases_from_launch with mode=hide) when unsure.
+- If no API token is configured, use configure_allure_token (stored for the session only).`
+
 func (s *Server) handleInitialize(req *JSONRPCRequest) *JSONRPCResponse {
 	var initReq InitializeRequest
 	if len(req.Params) > 0 {
@@ -383,6 +408,7 @@ func (s *Server) handleInitialize(req *JSONRPCRequest) *JSONRPCResponse {
 	resp.Capabilities.Resources.Subscribe = true
 	resp.ServerInfo.Name = "allure-mcp-server"
 	resp.ServerInfo.Version = Version
+	resp.Instructions = serverInstructions
 
 	s.logger.Info("initialize response sent", map[string]any{
 		"version": resp.ProtocolVersion,

internal/mcp/server_test.go

@@ -106,6 +106,14 @@ func TestServer_InitializeOverSSE(t *testing.T) {
 	if string(parsed.ID) != "1" {
 		t.Errorf("id = %s, want 1", parsed.ID)
 	}
+
+	result, ok := parsed.Result.(map[string]any)
+	if !ok {
+		t.Fatalf("result is not an object: %T", parsed.Result)
+	}
+	if instr, _ := result["instructions"].(string); instr == "" {
+		t.Error("initialize response should include non-empty instructions for tool discoverability")
+	}
 }
 
 func TestServer_ToolsListOverSSE(t *testing.T) {

internal/tools/registry.go

@@ -392,7 +392,7 @@ func (r *Registry) GetResource(uri string) *Resource {
 // autoAnnotate returns MCP tool annotations derived from the tool's name.
 //
 // Naming conventions:
-//   - get_* / list_* / search_* / suggest_* / validate_* → readOnly
+//   - get_* / list_* / find_* / search_* / suggest_* / validate_* → readOnly
 //   - delete_* / bulk_delete_* / detach_* → destructive write
 //   - everything else → non-destructive write
 func autoAnnotate(name string) map[string]any {
@@ -415,6 +415,7 @@ func autoAnnotate(name string) map[string]any {
 	readOnlyPrefixes := []string{
 		"get_",
 		"list_",
+		"find_",
 		"search_",
 		"suggest_",
 		"validate_",