NextFlows

Hi, this is my Academy MCP project.

https://nextflows.ai/academy

Notes & FAQ Search MCP Server

What It Does

Notes & FAQ Search is an offline TypeScript MCP server for searching, retrieving, listing, adding, updating, and deleting locally stored notes and FAQs.

The server works fully offline at runtime and uses local JSON fixture data instead of a cloud database or external API.

It exposes seven MCP tools:

• Search notes.

• Search FAQs.

• Retrieve a complete note by ID.

• List notes with optional tag filtering.

• Add a new note safely to local storage.

• Update an existing note safely.

• Delete an existing note safely.

The server also exposes two read-only MCP resources:

• notes://index

• faq://index

Related MCP server: recall-mcp

Requirements

Before installing the project, make sure you have:

• Git

• Node.js 20 or later

• npm

Check Node.js and npm with:

node --version
npm --version

Install

Clone the repository:

git clone https://github.com/SajaAsfour/mcp-Notes-FAQ-Search-MCP-server.git

Enter the project directory:

cd mcp-Notes-FAQ-Search-MCP-server

Install the dependencies:

npm install

Run

Start the MCP server in development mode:

npm run dev

The server runs over stdio and waits for an MCP client connection.

To stop it, press:

Ctrl+C

Note: If you are using MCP Inspector for testing, you do not need to run npm run dev separately. The MCP Inspector command below starts the server for the Inspector connection.

Optional smoke tests can be run with:

npm test

Schema checks can be run with:

npm run check:schemas

TypeScript type checking can be run with:

npm run typecheck

MCP Inspector

From the project root, launch MCP Inspector with:

npx -y @modelcontextprotocol/inspector npx tsx src/index.ts

Important: Use either npm run dev with another MCP client, or the MCP Inspector command for Inspector-based testing. You do not need to run both at the same time.

When the Inspector opens, connect to the server and open the Tools section.

You should see all seven tools listed below.

First Successful Tool Call

To verify that the server is working, you can make your first tool call using get_note:

1. Open the Tools section in MCP Inspector.

2. Select get_note.

3. Enter the following input:

{
  "note_id": "note-001"
}

4. Run the tool.

A successful call should return the requested note data in the Inspector response.

Tools

limit must be a positive integer no greater than 20.

For update_note, at least one of title, content, or tags must be provided together with a valid note_id.

Example Prompts

Search notes

Ask the server to:

Find notes about MCP tools and resources.

Use search_notes with:

{
  "query": "MCP tools and resources",
  "limit": 5
}

Search FAQs

Ask the server to:

Find the FAQ that explains what an MCP tool is.

Use search_faqs with:

{
  "query": "What is an MCP tool?",
  "limit": 5
}

Get a note

Ask the server to:

Get the full note with ID note-001.

Use get_note with:

{
  "note_id": "note-001"
}

List notes

Ask the server to:

List up to five notes.

Use list_notes with:

{
  "limit": 5
}

Add a note

Ask the server to:

Add a note about testing the MCP server.

Use add_note with:

{
  "title": "MCP Testing",
  "content": "Use MCP Inspector to test the server tools.",
  "tags": ["mcp", "testing"]
}

add_note writes the validated note to data/notes.json. This changes only the local copy of the project's fixture data on your machine; it does not modify any shared database or GitHub data.

Update a note

Ask the server to:

Update note-001 with a new title.

Use update_note with:

{
  "note_id": "note-001",
  "title": "Updated MCP Testing Note"
}

You can also update more than one field in the same request:

{
  "note_id": "note-001",
  "title": "Updated MCP Testing Note",
  "content": "This note was updated through the MCP server.",
  "tags": ["mcp", "testing", "updated"]
}

update_note modifies only the fields provided in the request. Fields that are not included remain unchanged. The note keeps the same ID after the update.

Delete a note

Ask the server to:

Delete the note with ID note-006.

Use delete_note with:

{
  "note_id": "note-006"
}

## Example Conversations

See `examples/conversations.md` for model interaction examples covering the server's search, retrieval, listing, and mutation workflows.

## Local Data

The project stores its local fixture data in:

```text
data/notes.json
data/faqs.json

The server remains offline at runtime.

Read operations use the local JSON data, while add_note and update_note can modify the local data/notes.json file.

Because these mutations are local, changes made during testing affect only the local project copy unless those data changes are intentionally committed to Git.

Troubleshooting

1. npm or Node.js is not available

If commands such as npm install or npm run dev are not recognized, confirm that Node.js 20 or later and npm are installed:

node --version
npm --version

Install or update Node.js if the commands are missing or the Node.js version is older than 20.

2. The server or MCP Inspector does not start

Make sure you are running commands from the repository root and that dependencies were installed first:

npm install

Then launch Inspector with the exact command:

npx -y @modelcontextprotocol/inspector npx tsx src/index.ts

If you are using MCP Inspector, do not start npm run dev at the same time.

The project uses stdio for MCP communication, so avoid adding normal output to stdout while the MCP server is running.

3. A tool returns an input validation error

Check that the input matches the expected schema.

For search tools:

• query must not be empty.

• limit, when provided, must be a positive integer from 1 to 20.

For get_note and update_note, use an ID in this format:

note-001

For example:

{
  "note_id": "note-001"
}

Do not use file paths or values such as ../etc/passwd as note IDs.

For update_note, provide at least one field to change:

{
  "note_id": "note-001",
  "title": "Updated Title"
}

An update containing only note_id should be rejected because no change was requested.

4. update_note cannot find the note

Use list_notes first to confirm the ID of the note you want to update.

Then call update_note using the exact note ID returned by the server.

5. Claude or another MCP host does not show update_note

Confirm that your local project is on the branch or commit containing the new tool and that registerUpdateNoteTool(server) is registered in src/index.ts.

Then fully restart the MCP host so it performs tool discovery again.

License

This project is licensed under the MIT License. See the LICENSE file for details.