# RevCent MCP Overview: Projects

AI/MCP-focused overview of RevCent Projects, Project entity associations, and Project Notes.

A Project can represent a business, an objective, an operational initiative, a reporting workspace, an external-agent source of truth, or any durable AI/MCP context container that should be reused over time.

---

# Project

## What Is a Project?

A **Project** is a durable RevCent context container that behaves like a **pseudo repository** for AI/MCP work.

A Project can store:

- the Project purpose through its `name` and `description`,
- associated RevCent entities,
- Project Notes,
- decisions made,
- historical context,
- assumptions,
- setup progress,
- reporting findings,
- external-agent operating context,
- follow-up work,
- warnings and constraints.

Simple model:

```text
Project = pseudo repository for AI/MCP context
Project description = README / source-of-truth purpose statement
Project entities = associated RevCent objects / repository index
Project notes = commit log, decision log, research log, and working memory
```

Projects are useful for AI because they prevent every future interaction from needing all historical context in the prompt. Instead of keeping a full account history, onboarding history, reporting history, or agent instruction history in active conversation context, AI/MCP can retrieve the relevant Project and its recent notes only when needed.

Token-saving model:

```text
Without Projects:
AI must keep or reconstruct large amounts of historical context.

With Projects:
AI retrieves the relevant Project, associated entities, and notes only when needed.
```

This makes Projects a practical way to reduce token usage, avoid repeated discovery work, and keep AI/MCP actions grounded in durable account-specific context.

---

## Core Principle

AI/MCP should use a Project whenever work has an ongoing purpose, repeated context, associated RevCent entities, historical decisions, or future follow-up.

Important rule:

```text
A Project should represent the durable context for a business, objective, initiative, workflow, report, agent, or operation.
```

Projects should not be thought of only as business containers. A Project can be used for:

- onboarding a business,
- implementing a WooCommerce store,
- managing a RevCent setup initiative,
- analyzing business metrics,
- creating recurring reports,
- tracking optimization recommendations,
- serving as a source of truth for an external agent,
- recording operational notes,
- grouping related RevCent entities,
- preserving context for future AI conversations.

When performing RevCent work related to a Project, AI/MCP should use Project Notes to track meaningful changes, decisions, and findings.

---

## Why Projects Matter

Projects give AI/MCP a durable memory trail for work that may span multiple sessions, users, agents, or operations.

Without Projects, future AI interactions may not know:

- what the current objective is,
- why an entity was created,
- which business, initiative, report, or agent it belongs to,
- which user decision led to a configuration,
- which setup stage was completed,
- which metrics were already analyzed,
- what advice was already given,
- which entities work together,
- whether a profile is global or custom/specific,
- whether a change was temporary, experimental, or permanent,
- what assumptions were used,
- what still needs to be configured or reviewed.

With Projects, AI/MCP can retrieve scoped context and avoid:

- repeating work,
- making incorrect assumptions,
- modifying the wrong global object,
- losing reporting history,
- forgetting why an agent behaves a certain way,
- mixing unrelated objectives together,
- wasting tokens by loading broad account history unnecessarily.

---

## When to Create or Use a Project

Create or use a Project when work has durable context.

Good reasons to create or use a Project:

- onboarding a business,
- setting up or modifying a RevCent account,
- tracking a WooCommerce/shop implementation,
- managing an operational objective,
- creating reports or recurring analysis,
- storing external-agent source-of-truth context,
- grouping related entities,
- tracking decisions and follow-up work,
- preserving context across multiple AI/MCP sessions.

Do not create a Project for every tiny one-off action if there is no lasting context. Instead, use an existing relevant Project when one exists.

Decision rule:

```text
If future AI/MCP would benefit from knowing this context, use a Project.
```

---

## Project Use Cases

### Business Onboarding

If a RevCent user is onboarding a business, create or use a Project for that specific business.

Examples:

```text
Acme Skincare Initial RevCent Account Setup
Acme Skincare RevCent Implementation
Acme Skincare WooCommerce Store Launch Setup
Acme Skincare Subscription Billing Migration
```

A business onboarding Project should track stages such as:

- campaign setup,
- products,
- product groups,
- payment profiles,
- gateways,
- PayPal accounts,
- third-party shops,
- shipping profiles,
- fulfillment accounts,
- tax profiles,
- subscription profiles,
- email templates,
- SMTP profiles,
- customer portal,
- AI Assistants,
- AI Voice Agents,
- tracking domains,
- functions,
- secure forms.

If a user onboards multiple businesses, each onboarded business should generally have its own Project so Project names, descriptions, notes, and associated entities remain scoped correctly.

### Operational Objective or Initiative

A Project can represent an objective or type of business operation, even when it is not limited to one onboarded business.

Examples:

```text
Q3 Revenue Optimization Initiative
Subscription Churn Reduction Project
Chargeback Mitigation Review
Gateway Routing Performance Analysis
Renewal Recovery Automation Rollout
Customer Portal Improvement Project
Email Deliverability Cleanup
```

Use this type of Project when the user wants to track work around a goal, workflow, or operational improvement.

The Project should track:

- the objective,
- scope and boundaries,
- relevant entities,
- analysis performed,
- actions taken,
- recommendations given,
- follow-up tasks,
- user decisions,
- risks or assumptions.

### Business Metrics, Reporting, and Advice

A Project can be used as a reporting and analysis workspace.

Examples:

```text
Weekly Revenue Reporting
Monthly Subscription Metrics Review
Q3 Retention Analysis
Gateway Approval Rate Monitoring
Product Performance Reporting
```

This is useful when AI/MCP is expected to repeatedly analyze RevCent data, create reports, compare trends, or provide business advice.

A reporting Project should track:

- the report purpose,
- date ranges reviewed,
- metrics analyzed,
- BigQuery tables or queries used when relevant,
- findings,
- recommendations,
- assumptions,
- follow-up questions,
- whether advice was accepted or rejected,
- future reporting cadence if applicable.

Project Notes should preserve the reasoning trail without requiring the entire analysis history to stay in the active conversation.

### External-Agent Source of Truth

A Project can serve as the source of truth for an external AI agent, MCP client, automation, or operational assistant.

Examples:

```text
External Support Agent Source of Truth
Renewal Recovery Agent Operating Context
WooCommerce Onboarding Agent Project
Reporting Agent Knowledge Base
Chargeback Review Agent Workspace
```

For external agents, the Project description should clearly explain:

- the agent objective,
- what the agent is allowed to do,
- what the agent should not do,
- relevant RevCent entities,
- escalation rules,
- required user confirmations,
- how notes should be written,
- what context must be retrieved before acting.

Project Notes should record agent-relevant updates such as:

- new instructions,
- decisions,
- observed issues,
- entity changes,
- safety restrictions,
- escalation requirements,
- user-approved behavior changes.

External agents should not rely only on active runtime context. They should retrieve the relevant Project and Project Notes before acting.

### Notes Repository / Operating Journal

A Project can be used primarily as a notes repository for a user, AI/MCP, or external agent.

Examples:

```text
Customer Support Process Notes
Internal RevCent Account Decisions
Open Follow-Up Items
Implementation Risk Log
AI Agent Working Memory
```

Use this type of Project when the main purpose is to preserve durable notes, decisions, observations, warnings, or instructions.

---

## Project Description Guidance

The Project description is the Project's README-like source-of-truth statement.

It should explain:

- the Project purpose,
- the business, objective, report, workflow, or agent it applies to,
- the intended scope,
- systems or RevCent areas involved,
- associated entity categories,
- whether the Project is initial setup, migration, reporting, agent context, or modification,
- warnings or special requirements,
- what future AI/MCP should review before acting.

A good Project description helps future AI/MCP understand why the Project exists before reviewing associated entities or notes.

---

## Project Naming Guidance

Use names that describe the Project purpose clearly.

Project names may be:

- business-specific,
- objective-specific,
- reporting-specific,
- agent-specific,
- workflow-specific,
- notes/context-specific.

Good Project names:

```text
Acme Skincare Initial RevCent Account Setup
Acme Skincare WooCommerce Implementation
Acme Skincare Subscription Billing Migration
Q3 Revenue Optimization Initiative
Monthly Subscription Metrics Review
Gateway Approval Rate Monitoring
External Renewal Recovery Agent Source of Truth
Customer Support Process Notes
```

Avoid vague names:

```text
Setup
Changes
Stuff
New Project
Notes
Main
```

When the Project is business-specific, include the business name. When the Project is objective-specific, include the objective. When the Project is agent-specific, include the agent purpose.

---

## Searching Projects

Use `SearchProjects` when AI/MCP needs to locate a Project by Project text or by a known associated entity.

`SearchProjects` supports `search_term` for full-text search across Project `name` and `description`. It can also search for Projects that have a specific associated entity ID, such as a Campaign, Product, Payment Profile, AI Assistant, Function, Third-Party Shop, Third-Party Integration, Tracking Domain, Tax Profile, or other supported Project association.

Use `SearchProjects` when the user provides a business name, objective phrase, report name, agent purpose, or entity ID. Use `GetProjects` when browsing paginated Project lists is more appropriate. After selecting a match, use `GetProject` to retrieve the full Project details and associated entities.

---

## What `GetProject` Provides

`GetProject` retrieves the details of a specific Project.

It returns:

- Project ID,
- Project name,
- Project description,
- created/updated timestamps,
- associated entities grouped by entity type.

`GetProject` is important because it gives AI/MCP a quick map of entities associated with the Project.

Examples of Project entity groups can include:

- AI Assistants,
- AI Prompts,
- AI Voice Agents,
- AI Voice Snippets,
- Bin Profiles,
- Campaigns,
- Customer Groups,
- Customer Portals,
- Email Templates,
- Fulfillment Accounts,
- Functions,
- Gateways,
- Gateway Groups,
- Key Values,
- Payment Profiles,
- PayPal Accounts,
- Products,
- Product Groups,
- Shipping Profiles,
- SMTP Profiles,
- Subscription Profiles,
- Third-Party Shops,
- Third-Party Integrations,
- Tracking Domains,
- URL Parameter Sets,
- and other RevCent entity types supported by Project association operations.

For each entity returned by `GetProject`, AI/MCP should use the entity's respective `Get...` operation for full details.

Example:

```text
GetProject returns a Product ID
    ↓
Use GetProduct to retrieve the full Product
```

---

## Creating a Project

Use `CreateProject` to create a new Project.

Required:

| Field | Description |
|---|---|
| `name` | Project name. |

Optional:

| Field | Description |
|---|---|
| `description` | Project description. |

Important:

```text
Create the Project only when there is durable context worth preserving.
Use a clear name and README-like description so future AI/MCP can understand the purpose quickly.
```

---

## Editing a Project

Use `EditProject` to edit Project `name` and/or `description`.

Required:

| Field | Description |
|---|---|
| `project_id` | 20-character Project ID. |

Optional:

| Field | Description |
|---|---|
| `name` | New Project name. |
| `description` | New Project description. |

Important:

```text
Only provide the fields that should be edited.
```

---

## Project Entity Associations

Project entity associations show which RevCent objects belong to the Project.

Important:

```text
Associated entities tell AI/MCP what belongs to the Project.
Project Notes explain why those entities matter.
```

Association alone is not enough. Always use notes to explain purpose, decision history, and operational context.

### Associating Entities with a Project

Use `ProjectAssociateEntity` to associate an existing RevCent entity with a Project.

Use `ProjectAssociateEntity` when:

- an entity was created as part of the Project,
- an existing entity is now part of the Project scope,
- a related object should be visible when future AI/MCP calls `GetProject`,
- AI/MCP needs future context about which entities belong together,
- the Project should track a WooCommerce/shop setup, subscription setup, payment setup, email setup, AI setup, fulfillment setup, reporting workspace, agent workspace, or similar configuration group.

Required:

| Field | Description |
|---|---|
| `project_id` | 20-character Project ID. |

Entity fields:

| Field | Description |
|---|---|
| `entity_type` | The RevCent entity type to associate. |
| `entity_id` | 20-character entity ID. If associating a `key_value`, use the key instead of an ID. |

After associating an entity, create a Project Note explaining why the entity was associated.

### Disassociating Entities from a Project

Use `ProjectDisassociateEntity` to remove an existing entity association from a Project.

Disassociation should be intentional because removing an entity from a Project can reduce future AI/MCP context.

Use `ProjectDisassociateEntity` when:

- an entity was associated with the wrong Project,
- an entity no longer belongs to the implementation/change workflow,
- a duplicate or obsolete association should be removed,
- the Project scope has changed,
- the user explicitly wants to detach the entity from the Project.

Required:

| Field | Description |
|---|---|
| `project_id` | 20-character Project ID. |

Entity fields:

| Field | Description |
|---|---|
| `entity_type` | The RevCent entity type to disassociate. |
| `entity_id` | 20-character entity ID. If disassociating a `key_value`, use the key instead of an ID. |

After disassociating an entity, create a Project Note explaining why it was removed.

Disassociating an entity from a Project does **not** necessarily delete the entity itself.

Important:

```text
ProjectDisassociateEntity removes the Project association.
It should not be treated as deleting the underlying RevCent entity.
```

Use delete/remove operations only when the user explicitly wants to delete or remove the underlying object and the relevant operation supports that action.

### Supported Project Association Entity Types

`ProjectAssociateEntity` and `ProjectDisassociateEntity` support the following `entity_type` values:

| `entity_type` | Entity |
|---|---|
| `campaign` | Campaign |
| `ai_assistant` | AI Assistant |
| `ai_voice_agent` | AI Voice Agent |
| `ai_voice_snippet` | AI Voice Snippet |
| `ai_prompt` | AI Prompt |
| `key_value` | Key Value. Use the key as `entity_id`. |
| `bin_profile` | BIN Profile |
| `customer_group` | Customer Group |
| `customer_portal` | Customer Portal |
| `email_template` | Email Template |
| `fulfillment_account` | Fulfillment Account |
| `product` | Product |
| `product_group` | Product Group |
| `custom_function` | Function / Custom Function |
| `gateway` | Gateway |
| `gateway_group` | Gateway Group |
| `smtp_profile` | SMTP Profile |
| `paypal_account` | PayPal Account |
| `payment_profile` | Payment Profile |
| `shipping_profile` | Shipping Profile |
| `subscription_profile` | Subscription Profile |
| `url_parameter_set` | URL Parameter Set |
| `third_party_shop` | Third-Party Shop / Shop |
| `third_party_integration` | Third-Party Integration |
| `tracking_domain` | Tracking Domain |

Important:

```text
Use the exact `entity_type` enum value expected by the operation schema.
```

For Functions, the project association entity type is:

```text
custom_function
```

not simply:

```text
function
```

---

## Related Project Operations

| Operation | Purpose |
|---|---|
| `CreateProject` | Create a Project. Required field: `name`; optional field: `description`. |
| `EditProject` | Edit Project `name` and/or `description` using `project_id`. Only provide fields that should change. |
| `GetProject` | Retrieve one Project by `project_id`, including associated entities grouped by entity type. |
| `GetProjects` | Retrieve a paginated list of Projects with names and descriptions. Use `GetProject` for associated entities. |
| `SearchProjects` | Search Projects by name/description search term or by associated entity ID. Use before creating duplicate Projects or when an entity ID should locate its Project context. |
| `ProjectAssociateEntity` | Associate an existing RevCent entity with a Project. Requires `project_id`; use `entity_type` and `entity_id` to identify the entity to associate. |
| `ProjectDisassociateEntity` | Disassociate an existing RevCent entity from a Project. Requires `project_id`; use `entity_type` and `entity_id` to identify the entity to remove from the Project. |

---

## Operation Links

| Operation | Link |
|---|---|
| CreateProject | `https://revcent.com/documentation/markdown/mcp/operation/CreateProject.md` |
| EditProject | `https://revcent.com/documentation/markdown/mcp/operation/EditProject.md` |
| GetProject | `https://revcent.com/documentation/markdown/mcp/operation/GetProject.md` |
| GetProjects | `https://revcent.com/documentation/markdown/mcp/operation/GetProjects.md` |
| ProjectAssociateEntity | `https://revcent.com/documentation/markdown/mcp/operation/ProjectAssociateEntity.md` |
| ProjectDisassociateEntity | `https://revcent.com/documentation/markdown/mcp/operation/ProjectDisassociateEntity.md` |

---

# Project Notes

## What Project Notes Are For

Project Notes are the Project's durable working memory.

They can function as:

- a change log,
- a decision log,
- a research log,
- an implementation journal,
- a reporting history,
- a source-of-truth update stream for external agents,
- a compact replacement for keeping all historical context in active AI memory.

Project Notes should be used as the ongoing memory of the Project. They explain why entities matter, what changed, what was decided, what was learned, and what future AI/MCP or external agents should know.

---

## Project Note `title` and `content`

Project Notes have two important user-written fields:

| Field | Purpose | AI/MCP Guidance |
|---|---|---|
| `title` | Short summary shown when retrieving a list of Project Notes. | Keep small, concise, and descriptive. The title should help AI/MCP decide whether to retrieve the full note content. Minimum length: 1 character. Maximum length: 100 characters. |
| `content` | Full note body containing useful context, details, IDs, decisions, findings, and follow-up. | Keep complete enough for future AI/MCP to understand without the original conversation. Minimum length: 1 character. Maximum length: 5000 characters. |

Important retrieval behavior:

```text
GetProjectNotes returns note metadata and title only.
GetProjectNotes does not return note content.
Use GetProjectNote with the project_note_id to retrieve the full content of a specific note.
```

Because list retrieval only returns `title`, note titles are not decorative. They are the Project Note index. Future AI/MCP will often scan note titles first, then retrieve only the notes whose titles look relevant. This saves tokens and avoids loading every historical note into context.

Title rules:

```text
- Keep under 100 characters.
- Include the main action, decision, or finding.
- Include the relevant business/objective/report/agent when helpful.
- Do not use vague titles such as "Update", "Note", "Changes", or "Follow-up".
- Do not put the full note body in the title.
```

Content rules:

```text
- Maximum length is 5000 characters.
- Keep it concise, but complete enough to stand alone.
- Include IDs and entity names when the note relates to RevCent entities.
- Include assumptions and user decisions when they affect future behavior.
- Include explicit warnings when future AI/MCP should avoid changing something without confirmation.
```

Project Notes should be concise but useful. Do not rely on the active conversation to explain the note later. Write the content so a future AI/MCP call, external agent, or user can understand the note on its own.

---

## When to Create a Project Note

Create a Project Note whenever AI/MCP performs or helps coordinate a meaningful RevCent account change, analysis, or decision.

Examples:

- created a Product,
- edited a Product,
- created a Subscription Profile,
- edited a Payment Profile,
- created a Shipping Profile,
- edited a Tax Profile,
- created a WooCommerce Shop,
- validated/fixed a Shop,
- imported shop shipping methods,
- imported alternate payments,
- imported products,
- created an Email Template,
- created or edited SMTP Profile,
- created Customer Portal,
- created AI Assistant,
- created AI Voice Agent,
- initialized tracking domain DNS/SSL,
- created Secure Form,
- changed fulfillment settings,
- created or edited Functions,
- created or edited third-party integrations,
- associated an entity with a Project,
- disassociated an entity from a Project,
- ran a business metrics analysis,
- created a report,
- gave optimization advice,
- updated an external agent's source-of-truth context,
- made a significant decision even if no operation was run.

Do not create noisy notes for tiny one-off actions that have no future context value. Notes should improve future AI/MCP understanding.

---

## Recommended Project Note Content Structure

Project Notes should be structured enough for future AI to understand quickly.

A Project Note should be created with both a `title` and `content`.

Recommended content structure:

```text
[YYYY-MM-DD] Action / decision / finding summary

Context:
- What the user wanted
- Why the work was done
- Whether this was business-specific, objective-specific, reporting-related, or agent-related
- Any important decision or constraint

Changes / Findings:
- Operation(s) run, if any
- Entity names and IDs, if any
- Key settings changed, if any
- Metrics/findings/recommendations, if analysis was performed

Related entities:
- Project ID
- Campaign ID
- Product IDs
- Profile IDs
- Shop IDs
- Integration IDs
- AI/agent IDs
- Other related IDs

Follow-up:
- Remaining setup steps
- Warnings
- Items requiring explicit user confirmation
- Future analysis or agent behavior notes
```

---

## Project Notes by Work Type

### Entity Creation

When creating a new entity, note:

```text
Entity type
Entity name
Entity ID
Purpose
Key settings
Related entities
Why it was created
Whether it is business-specific, objective-specific, or agent-related
```

### Entity Edits

When editing an existing entity, note:

```text
Entity type
Entity name
Entity ID
Previous purpose/state if known
Fields/settings changed
Reason for edit
Impact scope
Whether user explicitly confirmed
```

This is especially important for globally used entities.

Examples of globally impactful objects:

- Subscription Profiles,
- Payment Profiles,
- Shipping Profiles,
- Tax Profiles,
- Email Templates,
- SMTP Profiles,
- Customer Portal configuration,
- Fulfillment Accounts,
- Functions,
- AI Assistants,
- AI Voice Agents,
- Gateways,
- Gateway Groups.

If an edit affects many customers/subscriptions/sales, the Project Note should clearly indicate that the user confirmed the scope.

### Metrics, Reports, and Advice

When using a Project for reporting or analysis, Project Notes should preserve the important analysis context.

Record:

```text
Report name or objective
Date range analyzed
Metrics reviewed
Queries or data sources used, when relevant
Key findings
Recommendations
Confidence/assumptions
User decisions
Follow-up analysis needed
```

### External Agents

When a Project is used as an external-agent source of truth, Project Notes should be written so another agent can safely use them without needing the original conversation.

Record:

```text
Agent objective
Allowed actions
Disallowed actions
Relevant entities
Current strategy
Safety rules
Escalation requirements
User-approved decisions
Last known state
Follow-up tests
```

### Custom Customer-Specific Work

Projects are useful when creating customer-specific or subscription-specific configuration, such as when a customer requires a custom renewal cycle.

AI/MCP should avoid editing a globally used Subscription Profile. Instead, it should create a specific/custom profile where appropriate and record the reason in the Project Note.

### WooCommerce / Shop Work

For WooCommerce or other third-party shop setup, the Project should track:

- shop creation,
- domain/tracking DNS status,
- RevCent Payments plugin validation,
- FixUserShop results,
- WooCommerce shipping method retrieval/import,
- alternate payment retrieval/import,
- PayPal account association,
- product retrieval/import,
- product mapping,
- shipping method mapping,
- payment method mapping,
- subscription billing decision,
- trials and renewals requiring RevCent profiles,
- customer portal embed plan,
- email template ownership,
- AI Assistant and AI Voice Agent support setup.

### AI and Automation

Projects should also track AI/automation configuration.

Examples:

- AI Assistant created for customer support,
- AI Assistant created for subscription recovery,
- AI Voice Agent created for inbound support,
- AI Voice Agent created for outbound renewal recovery,
- Functions created for events or integrations,
- Email Templates connected to purchase/shipment/subscription events,
- Tracking domain setup completed,
- Secure Form created for payment collection,
- External agent operating context created or updated.

Project Notes should describe:

```text
Automation purpose
Trigger/event
Affected entities
Safety rules
Customer verification requirements
Follow-up testing
```

---

## Creating Project Notes

Use `CreateProjectNote` to create a note for a Project.

Required:

| Field | Description |
|---|---|
| `project_id` | 20-character Project ID associated with the note. |
| `title` | Short Project Note title. Minimum 1 character, maximum 100 characters. Used when listing notes. |
| `content` | Full Project Note content. Minimum 1 character, maximum 5000 characters. Retrieved with `GetProjectNote`. |

Important:

```text
The title should summarize what the note is about.
The content should preserve the durable context.
GetProjectNotes returns titles, not content.
Future AI/MCP depends on good titles to decide which full notes to retrieve.
```

---

## Editing Project Notes

Use `EditProjectNote` to edit an existing Project Note.

Required:

| Field | Description |
|---|---|
| `project_note_id` | 20-character Project Note ID. |

Optional:

| Field | Description |
|---|---|
| `project_id` | 20-character Project ID associated with the note. |
| `title` | Updated Project Note title. Minimum 1 character, maximum 100 characters. |
| `content` | Updated Project Note content. Minimum 1 character, maximum 5000 characters. |

Important:

```text
Only provide the fields that should be edited.
If only the content should change, only include content.
If only the title should change, only include title.
```

Prefer editing a note to correct or clarify important context. Do not delete notes casually because they preserve history.

---

## Searching Project Notes

Use `SearchProjectNotes` when AI/MCP needs to find Project Note history by keyword, phrase, decision, warning, entity ID, or other text that may appear in note titles or content.

`SearchProjectNotes` requires `search_term`. Provide `project_id` when the search should be limited to one Project. This is useful when the relevant Project is known and AI/MCP needs to find a prior decision, warning, setup note, report finding, or external-agent instruction without paging through date ranges.

Use `GetProjectNotes` for date-range note indexes and `SearchProjectNotes` for targeted keyword search. Use `GetProjectNote` when a specific Project Note needs to be retrieved as the canonical single-note record.

---

## Getting Project Notes

Use `GetProjectNotes` to retrieve a list of Project Notes for a date range.

Required:

| Field | Description |
|---|---|
| `date_start` | Date range start as Unix timestamp in seconds. |
| `date_end` | Date range end as Unix timestamp in seconds. |
| `limit` | Number of notes to return. Range 1 to 25. Default is 25. |
| `page` | Pagination page. |

Optional:

| Field | Description |
|---|---|
| `project_filter` | Array of Project IDs used to return notes for specific Projects. |

`GetProjectNotes` returns list metadata such as:

```text
- Project Note ID
- Project ID and Project name
- Title
- Created timestamp
- Updated timestamp
```

Important:

```text
GetProjectNotes does not return the note content.
Only the title is returned for each note.
Use GetProjectNote to retrieve the content of a specific note.
```

Best practices:

```text
- Use project_filter when working within a specific Project.
- Use the narrowest useful date range to avoid paging through old notes.
- Start with recent notes when only recent context is needed.
- Review note titles first.
- Retrieve full content only for notes that appear relevant.
```

Recommended retrieval workflow:

```text
GetProjectNotes with project_filter and date range
    ↓
Review returned titles and note IDs
    ↓
Select relevant project_note_id values
    ↓
GetProjectNote for each note whose content is needed
    ↓
Use the retrieved content before creating, editing, analyzing, or advising
```

---

## Getting One Project Note

Use `GetProjectNote` when AI/MCP needs the full content of a Project Note.

Required:

| Field | Description |
|---|---|
| `project_note_id` | 20-character Project Note ID. |

`GetProjectNote` returns:

```text
- Project Note ID
- Project ID and Project name
- Title
- Content
- Created timestamp
- Updated timestamp
```

Use `GetProjectNote` after `GetProjectNotes` when a note title suggests the content may contain relevant history, decisions, IDs, warnings, reporting findings, or agent operating context.

---

## Deleting Project Notes

Use `DeleteProjectNote` only when the user explicitly wants to delete a Project Note.

Warning:

```text
Project Notes preserve project history and AI context.
```

Deleting notes can remove important context for future AI interactions and external agents. Prefer editing a Project Note for correction unless deletion is explicitly desired.

---

## Related Project Note Operations

| Operation | Purpose |
|---|---|
| `CreateProjectNote` | Create a note associated with a Project. Requires `project_id`, `title`, and `content`. |
| `EditProjectNote` | Edit a Project Note using `project_note_id`; only provide fields that should change, such as `title` and/or `content`. |
| `GetProjectNote` | Retrieve one Project Note by `project_note_id`, including its full `content`. |
| `GetProjectNotes` | Retrieve Project Note list results by date range; use `project_filter` to limit notes to one or more Projects. List results return titles, not full content. |
| `SearchProjectNotes` | Search Project Notes by keyword or phrase, optionally limited by `project_id`. Use when keyword search is more efficient than date-range browsing. |
| `DeleteProjectNote` | Delete a Project Note by `project_note_id`. Use carefully because notes preserve project history. |

---

## Operation Links

| Operation | Link |
|---|---|
| CreateProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/CreateProjectNote.md` |
| EditProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/EditProjectNote.md` |
| GetProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/GetProjectNote.md` |
| GetProjectNotes | `https://revcent.com/documentation/markdown/mcp/operation/GetProjectNotes.md` |
| DeleteProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/DeleteProjectNote.md` |

---

# Recommended AI/MCP Workflows

## General Workflow

Before creating, editing, analyzing, or reviewing RevCent configuration, AI/MCP should ask internally:

```text
Is this work part of an existing Project?
```

If yes:

```text
Use the existing Project.
Retrieve its details.
Use GetProjectNotes to review recent note titles, then GetProjectNote for any note content needed.
Continue tracking changes there.
```

If no:

```text
Create a new Project if the work has durable context, an ongoing objective, associated entities, future follow-up, or future AI/agent usefulness.
```

General workflow:

```text
SearchProjects when a term/entity ID is available, otherwise GetProjects
    ↓
Find an existing relevant Project
    ↓
If needed, GetProject for details and associated entities
    ↓
GetProjectNotes filtered by Project to review note titles
    ↓
GetProjectNote for relevant note content
    ↓
Perform the requested RevCent operation, analysis, or review
    ↓
ProjectAssociateEntity when an entity belongs to the Project
    ↓
CreateProjectNote documenting what changed, what was learned, or what was decided
```

---

## Workflow for Business Onboarding

```text
1. Use SearchProjects when a business name or entity ID is available; otherwise use GetProjects
2. Determine whether a relevant business-specific Project already exists
3. If not, CreateProject
4. CreateProjectNote describing onboarding scope and goals
5. Perform account setup operations
6. Associate created/relevant entities with Project
7. After each meaningful operation, CreateProjectNote
8. Use GetProject to review associated entities
9. Use GetProjectNotes to review setup note titles, then GetProjectNote for relevant full note content before future changes
```

---

## Workflow for Operational Objectives

```text
1. Define the objective and scope
2. Use SearchProjects when an objective phrase or entity ID is available; otherwise use GetProjects to find an existing objective-specific Project
3. If not found, CreateProject with a clear objective-focused name and description
4. Associate relevant entities
5. Use Project Notes to track work, findings, decisions, and follow-up
6. Before future work, retrieve the Project, review recent note titles with GetProjectNotes, and fetch relevant content with GetProjectNote
```

---

## Workflow for Metrics, Reports, and Advice

```text
1. Identify the reporting/analysis objective
2. Use SearchProjects when a report name, metric phrase, or entity ID is available; otherwise use GetProjects to find an existing reporting Project
3. If not found, CreateProject
4. GetProjectNotes to review prior analysis note titles, then GetProjectNote for relevant full note content
5. Run analysis or create report
6. CreateProjectNote with date range, metrics, findings, recommendations, and follow-up
7. Record user decisions if advice is accepted, rejected, or deferred
```

---

## Workflow for External Agents

```text
1. Identify the Project that acts as the agent source of truth
2. GetProject to retrieve purpose and associated entities
3. GetProjectNotes to retrieve recent operating-context titles, then GetProjectNote for relevant full note content
4. Agent performs only actions allowed by the Project description and notes
5. Agent creates Project Notes for meaningful findings, actions, or decisions
6. Agent avoids changing globally impactful entities unless the Project notes or user confirmation allow it
```

---

## Project Context Before Global Changes

Before modifying globally used entities, AI/MCP should review associated entities, use GetProjectNotes to inspect relevant note titles, and use GetProjectNote to retrieve full note content for any potentially relevant warnings or decisions.

Examples:

- editing a globally used Subscription Profile,
- changing Payment Profile routing,
- changing Shipping Profile rates,
- editing Tax Profile behavior,
- changing Email Templates,
- modifying Customer Portal,
- changing AI Assistant instructions,
- editing AI Voice Agent behavior,
- updating Function logic.

AI/MCP should explicitly confirm global-impact changes with the user and record that confirmation in a Project Note.

---

# Best Practices

1. Treat a Project as a pseudo repository for durable AI/MCP context.
2. Use Projects to reduce token usage by retrieving scoped context only when needed.
3. Use Projects for businesses, objectives, reporting, external-agent source-of-truth context, workflows, and durable notes.
4. Create or identify a Project before account setup, meaningful account changes, recurring analysis, or external-agent actions.
5. Read the Project and relevant Project Notes before acting.
6. Use Project descriptions as README-like source-of-truth statements.
7. Use Project Notes as the durable change log, decision log, research log, and working memory.
8. Record entity names and IDs in notes.
9. Record why a change was made, not only what changed.
10. Record user confirmations for global-impact changes.
11. Use `GetProjectNotes` first to review note titles by date range, or `SearchProjectNotes` when a keyword/phrase is known, then use `GetProjectNote` for relevant full content when needed.
12. Use narrow date ranges when retrieving notes to save time and tokens.
13. Use Project Notes for follow-up items and warnings.
14. Do not delete Project Notes unless explicitly requested.
15. Use `GetProject` to see associated entities.
16. Use `ProjectAssociateEntity` to associate newly created or relevant existing entities with the Project.
17. Use `ProjectDisassociateEntity` only when an entity should intentionally be removed from Project context.
18. Always create Project Notes when associating or disassociating entities.
19. Use each entity's specific `Get...` operation for full detail.
20. Keep Project Note titles concise and descriptive, and keep content complete enough for future AI context.
21. When uncertain whether work belongs to a Project, create or use a Project rather than leaving meaningful work untracked.
22. Keep unrelated businesses, objectives, reports, or external-agent contexts in separate Projects when combining them would confuse future AI/MCP.

---

# Common Mistakes to Avoid

Do not:

- think Projects are only for businesses,
- make meaningful account setup changes without a Project,
- use one generic Project for multiple unrelated onboarded businesses or objectives,
- create Project names or descriptions that do not identify the specific purpose,
- create RevCent entities without associating them with the relevant Project when they belong to that Project,
- create RevCent entities without recording notes,
- disassociate entities from Projects without documenting why,
- edit global profiles without documenting impact and confirmation,
- use Project Notes as vague logs with no IDs or context,
- create vague Project Note titles that do not help AI/MCP decide whether to retrieve the full note,
- put the entire note content in the title,
- delete Project Notes casually,
- assume future AI will remember why an entity was created unless the Project Note explains it,
- treat Project association alone as enough context without notes,
- modify project-related entities without reviewing recent Project Note titles and retrieving relevant full note content,
- load every old Project Note into context when a narrow date range or title review would be enough.

---

# Final AI/MCP Instruction

Projects should be used as the primary pseudo repository and context container for RevCent work.

A Project may represent a business, account setup, operational objective, reporting workspace, external-agent source of truth, workflow, or notes repository. The Project description should define the purpose and scope. Associated entities should identify the RevCent objects that belong to the Project. Project Notes should preserve the change history, decisions, findings, recommendations, warnings, and follow-up work.

Whenever AI/MCP creates, edits, deletes, associates, disassociates, analyzes, reports on, or meaningfully reviews RevCent configuration in a durable context, it should identify the relevant Project and use Project Notes to track what happened.

Use `GetProjectNotes` first to retrieve note titles and metadata by date range, or use `SearchProjectNotes` when searching note history by keyword or phrase. Use `GetProjectNote` only for specific notes whose full content is needed. This keeps Project Notes useful as a token-saving repository rather than forcing AI/MCP to load all historical context into every conversation.


---
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.