# RevCent MCP Guide: `CreateProjectNote`

AI/MCP-focused guide for creating a RevCent Project Note.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Project Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProject.md` | Explains how Projects work as pseudo repositories / durable AI context containers. |
| CreateProject | `https://revcent.com/documentation/markdown/mcp/operation/CreateProject.md` | Create the Project that the note will belong to. |
| GetProject | `https://revcent.com/documentation/markdown/mcp/operation/GetProject.md` | Retrieve Project details and associated entities before writing context-sensitive notes. |
| GetProjectNotes | `https://revcent.com/documentation/markdown/mcp/operation/GetProjectNotes.md` | Retrieve Project Note titles and metadata; content is not returned by this list operation. |
| SearchProjectNotes | `https://revcent.com/documentation/markdown/mcp/operation/SearchProjectNotes.md` | Search Project Notes by keyword or phrase, optionally within a specific Project, when note content or history needs to be found quickly. |
| GetProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/GetProjectNote.md` | Retrieve the full content of one Project Note. |
| EditProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/EditProjectNote.md` | Correct or clarify an existing Project Note. |

---

## Operation Summary

Operation:

```text
CreateProjectNote
```

Purpose:

```text
Create a Project Note associated with a Project.
```

A Project is a pseudo repository for a business, objective, workflow, report, external-agent source of truth, or other durable AI/MCP context. Project Notes preserve the Project's history, decisions, findings, warnings, and follow-up items so future AI/MCP does not need to keep all historical information in active context.

Use `CreateProjectNote` when new information should be saved as part of the Project's durable context.

---


## Project Note Search Note

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` and can optionally include `project_id` to limit the search to one Project. Use it when keyword search is more efficient than paging through `GetProjectNotes` by date. If the workflow needs a canonical single-note retrieval afterward, use `GetProjectNote` with the returned Project Note ID.

---

## Title, Content, and Metadata Caveat

Project Notes have three important user-provided context fields:

```text
title
content
metadata
```

`title` is the short, list-visible summary of the note. It is returned by `GetProjectNotes` and should help AI/MCP decide whether the full note needs to be retrieved. Keep it concise, descriptive, and specific.

`content` is the full note body. It is not returned by `GetProjectNotes` because it may be large. To read note content, AI/MCP must call `GetProjectNote` using the Project Note ID returned by `GetProjectNotes`.

`metadata` is an optional array of structured name/value pairs. Use metadata to store compact labels that can help future AI/MCP filter or identify notes, such as related entity type, entity ID, workflow, decision category, report period, risk level, or follow-up status.

Important:

```text
Do not rely on GetProjectNotes for full note context.
GetProjectNotes returns note titles and list metadata, and can be filtered by Project Note metadata.
Use GetProjectNote to retrieve the full content and metadata of a specific note.
```

---

## When to Use

Use `CreateProjectNote` when:

- a meaningful Project event should be preserved,
- a RevCent entity is created, edited, associated, or disassociated,
- a user decision should be saved,
- an implementation detail or warning matters for future AI/MCP,
- a follow-up item should be tracked,
- a report, analysis, or external-agent objective needs durable context,
- a Project's source-of-truth context changes.

---

## Metadata Property

Project Notes can include optional structured metadata as an array of name/value pairs.

Metadata item shape:

```json
{
  "name": "entity_type",
  "value": "payment_profile"
}
```

Metadata constraints:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `name` | string | Yes | Metadata name. Minimum 1 character, maximum 100 characters. |
| `value` | string | Yes | Metadata value. Minimum 1 character, maximum 255 characters. |

Use metadata for compact, filterable context such as entity type, entity ID, workflow name, decision category, report period, agent purpose, risk level, or follow-up status. Metadata should not replace the `title` or `content`; it should add structured labels that make Project Notes easier to filter and retrieve later.

---

## Input Schema

| Field | Type | Required | Description |
|---|---:|---:|---|
| `project_id` | string | Yes | 20-character Project ID that the note is associated with. |
| `title` | string | Yes | Short Project Note title. Minimum 1 character, maximum 100 characters. Returned by `GetProjectNotes`; should be useful as a quick index entry. |
| `content` | string | Yes | Full Project Note content. Minimum 1 character, maximum 5000 characters. Retrieved through `GetProjectNote`, not through `GetProjectNotes`. |
| `metadata` | array | No | Optional array of metadata name/value pair objects. Useful for structured labels that can be filtered when retrieving notes. |


Example with metadata:

```json
{
  "project_id": "XXXXXXXXXXXXXXXXXXXX",
  "title": "Payment profile routing decision",
  "content": "The user approved Amex routing through the backup gateway for this Project. Future changes should verify campaign scope before editing globally used payment profiles.",
  "metadata": [
    {
      "name": "entity_type",
      "value": "payment_profile"
    },
    {
      "name": "decision_category",
      "value": "payment_routing"
    },
    {
      "name": "follow_up_status",
      "value": "needs_verification"
    }
  ]
}
```

---

## Output Schema

Successful output can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `project_note_id` | 20-character Project Note ID. |
| `result` | Result message. |

---

## Recommended Workflow

```text
1. Identify the relevant Project.
2. Read the Project and recent Project Note titles when context is needed. Use `SearchProjectNotes` when a keyword, entity ID, warning, or decision needs to be found quickly.
3. Create the new Project Note with a concise title and useful content.
4. Store important entity IDs, decisions, warnings, and follow-up items in content.
5. Add metadata name/value pairs when structured filtering will help future retrieval.
6. Use GetProjectNote later when the full note body and metadata are needed.
```

---

## Best Practices

- Write titles as concise index entries, not full notes.
- Write content as the durable context future AI/MCP will need.
- Include relevant entity IDs and names when available.
- Use metadata for structured labels such as entity type, entity ID, workflow, status, report period, or decision category.
- Record why something happened, not only what happened.
- Keep content useful but within the 5000-character maximum.
- Create a new note for a new event instead of rewriting unrelated history.

---

## Common Mistakes to Avoid

Do not:

- omit `title`; it is required,
- put all important context only in `title`,
- use metadata as a replacement for the full note content,
- assume `GetProjectNotes` returns full note content,
- use vague titles that make retrieval difficult,
- create notes unrelated to a Project's objective or source-of-truth purpose,
- rely on Project entity association alone without durable note context.

---

## Final AI/MCP Instruction

Use `CreateProjectNote` to save durable Project context. Treat the title as the searchable/list-visible summary, the content as the full source-of-truth body, and metadata as optional structured labels that can help future AI/MCP filter and retrieve relevant Project Notes.


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