# RevCent MCP Guide: `SearchProjects`

AI/MCP-focused guide for searching RevCent Projects.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Project Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProject.md` | Explains Projects as durable AI/MCP pseudo repositories and source-of-truth context containers. |
| GetProjects | `https://revcent.com/documentation/markdown/mcp/operation/GetProjects.md` | Browse paginated Project lists when no useful search term or associated entity ID is known. |
| GetProject | `https://revcent.com/documentation/markdown/mcp/operation/GetProject.md` | Retrieve the full Project details and associated entities after selecting a search result. |
| CreateProject | `https://revcent.com/documentation/markdown/mcp/operation/CreateProject.md` | Create a new Project only after confirming an existing Project does not already match. |
| SearchProjectNotes | `https://revcent.com/documentation/markdown/mcp/operation/SearchProjectNotes.md` | Search Project Notes when the needed context may be in note history rather than Project name/description. |

---

## Operation Summary

Operation:

```text
SearchProjects
```

Purpose:

```text
Search previously created Projects using a search term or associated entity ID.
```

Use `SearchProjects` to quickly locate the relevant Project before creating a new Project, retrieving Project details, associating entities, or reviewing Project Notes.

---

## When to Use

Use `SearchProjects` when:

- the user provides a business name, Project name, objective phrase, report name, workflow name, or agent purpose,
- AI/MCP knows an associated entity ID and needs to find the Project that contains it,
- a targeted search is more efficient than paging through `GetProjects`,
- AI/MCP wants to avoid creating a duplicate Project,
- work should continue in an existing Project but the Project ID is unknown.

Use `GetProjects` instead when no useful search term or associated entity ID is available and AI/MCP needs to browse Projects by page.

---

## Input Schema

All fields are optional in the schema, but AI/MCP should provide at least one meaningful search field.

| Field | Description |
|---|---|
| `search_term` | Single search term or phrase. Searches Project `name` and `description` with full-text search. |
| Associated entity ID fields | One associated entity ID can be provided to find Project(s) linked to that entity. |

Supported associated entity ID filters include:

```text
campaign_id
ai_assistant_id
ai_voice_agent_id
ai_voice_snippet_id
ai_prompt_id
key_value_id
bin_profile_id
customer_group_id
customer_portal_id
email_template_id
fulfillment_account_id
product_id
product_group_id
custom_function_id
gateway_id
gateway_group_id
smtp_profile_id
paypal_account_id
payment_profile_id
shipping_profile_id
subscription_profile_id
url_parameter_set_id
third_party_shop_id
third_party_integration_id
tracking_domain_id
tax_profile_id
```

Example search by text:

```json
{
  "search_term": "Acme Skincare WooCommerce"
}
```

Example search by associated entity:

```json
{
  "product_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

## Output Summary

`SearchProjects` returns search results. Each result can include:

| Field | Meaning |
|---|---|
| `item_type` | Returned item type. For this operation, `project`. |
| `id` | 20-character Project ID. |
| `created_date_unix` | Project creation timestamp. |
| `name` | Project name. |
| `description` | Project description. |
| `url` | Direct RevCent URL for the Project details page. |
| `highlights` | Search fields and values that matched. |
| `score` | Search-engine relevance score; higher means a better match. |

---

## Recommended Workflow

```text
1. Use SearchProjects with a search_term or associated entity ID.
2. Review result names, descriptions, highlights, and scores.
3. Select the most relevant Project.
4. Use GetProject with the Project ID to retrieve details and associated entities.
5. Use GetProjectNotes or SearchProjectNotes when history, decisions, or warnings are needed.
6. Continue work in the existing Project or create a new Project only if no result clearly matches.
```

---

## Common Mistakes to Avoid

Do not:

- create a new Project without searching when a business name, objective, or entity ID is available,
- assume the top search result is correct without reviewing name, description, and highlights,
- use `SearchProjects` as a substitute for `GetProject` when associated entities are needed,
- provide broad vague search terms that may match unrelated Projects,
- search by entity ID and then modify the Project without retrieving it first.

---

## Final AI/MCP Instruction

Use `SearchProjects` to find existing Project context by text or associated entity ID. After selecting a result, use `GetProject` for full Project details and associated entities before acting.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.