# RevCent MCP Guide: `GetProjectNotes`

AI/MCP-focused guide for retrieving Project Note lists.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Project Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProject.md` | Explains Projects as pseudo repositories / durable AI context containers. |
| GetProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/GetProjectNote.md` | Retrieve the full content and metadata of a specific note returned by this list operation. |
| CreateProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/CreateProjectNote.md` | Create Project Notes with `title`, `content`, and optional `metadata`. |
| EditProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/EditProjectNote.md` | Correct or clarify an existing Project Note, including replacing metadata when needed. |
| 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. |

---

## Operation Summary

Operation:

```text
GetProjectNotes
```

Purpose:

```text
Return a paginated list of Project Notes by date range, optionally filtered by Project and/or metadata.
```

Projects act as pseudo repositories for RevCent work, objectives, reporting efforts, external-agent context, and business operations. Project Notes are the durable history inside a Project. They help AI/MCP save tokens by retrieving only relevant historical context when needed.

Use `GetProjectNotes` to scan note titles and basic list fields before deciding which full note content and metadata to retrieve with `GetProjectNote`. Use `SearchProjectNotes` when AI/MCP has a keyword or phrase and needs to search note history directly.

---

## 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 / Metadata Caveat

Project Notes can have a `title`, `content`, and optional `metadata`, but `GetProjectNotes` is a lightweight list operation.

Important:

```text
GetProjectNotes returns note titles and basic list fields only.
GetProjectNotes does not return Project Note content.
GetProjectNotes does not return Project Note metadata.
GetProjectNotes can filter by Project Note metadata using metadata_filter.
Use GetProjectNote to retrieve full content and metadata for a specific note.
```

The `title` should be treated as a concise index label for quick scanning. Metadata can be used as a filter when AI/MCP already knows structured labels such as entity type, entity ID, workflow, status, report period, or decision category. However, matched metadata values are not returned in the `GetProjectNotes` list response.

---

## Metadata Filtering

Project Notes can include optional structured metadata as an array of name/value pairs when created or edited. `GetProjectNotes` does not return those metadata pairs, but it can use them to narrow list results.

Metadata filter item shape:

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

Metadata filter item 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_filter` when structured labels can reduce irrelevant note results. Do not expect the matching metadata to appear in the response. To inspect a note's metadata, call `GetProjectNote` using the returned Project Note ID.

---

## Input Schema

Required fields:

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

Optional filters:

| Field | Description |
|---|---|
| `project_filter` | Array of 20-character Project IDs used to return notes related to specific Projects. |
| `metadata_filter` | Array of metadata name/value pair objects used to return notes matching one or more structured metadata labels. The matching metadata itself is not returned. |

Metadata filter example:

```json
{
  "date_start": 1717200000,
  "date_end": 1719791999,
  "limit": 25,
  "page": 1,
  "project_filter": ["XXXXXXXXXXXXXXXXXXXX"],
  "metadata_filter": [
    {
      "name": "entity_type",
      "value": "payment_profile"
    },
    {
      "name": "follow_up_status",
      "value": "needs_verification"
    }
  ]
}
```

Best practice:

```text
Use project_filter whenever working inside a known Project.
Use metadata_filter when structured labels can narrow the note list.
Use a narrow date range when only recent notes are needed.
```

---

## Output Summary

`GetProjectNotes` can return:

| Field | Meaning |
|---|---|
| `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. |
| `current_count` | Current number of items in the response. |
| `current_page` | Current page. |
| `total_count` | Total number of matching Project Notes. |
| `total_pages` | Total pages. |
| `results` | Array of Project Note list records. |

Each result can include:

| Field | Meaning |
|---|---|
| `id` | 20-character Project Note ID. |
| `project.id` | Associated Project ID. |
| `project.name` | Associated Project name. |
| `title` | Project Note title. |
| `created_date_unix` | Note creation timestamp. |
| `updated_date_unix` | Note update timestamp. |

Important:

```text
The results do not include content.
The results do not include metadata.
Use metadata_filter only to narrow list results by structured labels.
Use GetProjectNote when the full note content and metadata values are needed.
```

---

## When to Use

Use `GetProjectNotes` when:

- AI/MCP needs to review Project Note titles before acting,
- the relevant Project is known and notes should be filtered by Project,
- AI/MCP has metadata labels and should filter notes by structured name/value pairs,
- recent decisions, warnings, or follow-up items may affect the next operation,
- AI/MCP needs to identify which note IDs should be retrieved with `GetProjectNote`.

---

## Recommended Workflow

```text
Identify relevant Project
    ↓
GetProjectNotes with project_filter, optional metadata_filter, and date range
    ↓
Review returned titles and basic list fields
    ↓
Use GetProjectNote for relevant note IDs
    ↓
Use full note content and metadata before creating, editing, or deleting Project-related configuration
```

---

## Common Mistakes to Avoid

Do not:

- expect `content` in the `GetProjectNotes` response,
- expect `metadata` in the `GetProjectNotes` response,
- assume metadata filtering returns metadata values,
- make important decisions from titles alone when full note content or metadata is needed,
- omit `project_filter` when the relevant Project is known,
- omit `metadata_filter` when structured labels would avoid paging through irrelevant notes,
- page through old notes unnecessarily when a narrower date range would work,
- use this operation as a bulk reporting/export tool.

---

## Final AI/MCP Instruction

Use `GetProjectNotes` as the lightweight date-range index of Project Note titles and basic list fields. Use `project_filter` and `metadata_filter` to narrow results when possible, but do not expect content or metadata in the response. Use `SearchProjectNotes` for targeted keyword search across Project Notes, and fetch full content plus metadata for relevant notes using `GetProjectNote` when needed.


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