project-notes MCP Server

A custom Model Context Protocol (MCP) server written in TypeScript. It lets AI clients store, search, and summarize short notes about a codebase during a coding session.

Overview

This server exposes project notes through MCP tools (for actions) and a resource (for read-only context). It uses stdio transport, which makes it compatible with local AI clients like Cursor and Claude Desktop.

Notes are kept in memory for the lifetime of the server process. They are useful as a session scratchpad, not as permanent project documentation.

Features

Capability	Type	Description
add_note	Tool	Add a note with a title and content
search_notes	Tool	Search notes by keyword in title or content
notes://summary	Resource	Return note count and a list of all note titles

Tech Stack

• Runtime: Node.js (ESM)
• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod (auto-generates JSON Schema for tool inputs)
• Transport: stdio

Project Structure

mcp1/
├── src/
│   └── index.ts       # Server entry point
├── dist/
│   └── index.js       # Compiled output
├── .cursor/
│   └── mcp.json       # Cursor MCP configuration
├── package.json
├── tsconfig.json
└── README.md

Requirements

• Node.js 18+
• npm

Installation

npm install

Build

npm run build

This compiles TypeScript from src/ into dist/.

Run

npm start

The server communicates over stdio and waits for MCP client messages. Debug output is written to stderr only — never use console.log, as stdout must remain reserved for JSON-RPC.

On startup you should see:

[project-notes] Server started

Client Configuration

Cursor

Add or update .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "project-notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp1/dist/index.js"]
    }
  }
}

Replace the path with the absolute path to your built dist/index.js. Reload MCP servers in Cursor settings after building.

Claude Desktop

Add to your Claude Desktop config:

Platform	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "project-notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp1/dist/index.js"]
    }
  }
}

Restart Claude Desktop after saving.

Testing

Use the official MCP Inspector for interactive testing:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

From the inspector UI you can:

1. Call add_note with title and content
2. Call search_notes with a query
3. Read the notes://summary resource

Usage Examples

Once connected to a client, you can ask the AI to:

• Add a note: “Add a note: auth module was refactored to use JWT”
• Search notes: “Search notes for auth”
• List notes: “What project notes do we have?”

Example tool inputs:

{
  "title": "Auth refactor",
  "content": "JWT tokens now replace session cookies in src/auth/"
}

{
  "query": "auth"
}

Implementation Details

Tools vs Resources

• Tools are for actions the model can invoke (add_note, search_notes).
• Resources provide context the host can read without a tool call (notes://summary).

Using a resource for summaries avoids adding extra tools and helps keep the tool list small.

Input Validation

Tool parameters are defined with Zod schemas. The MCP SDK converts these into JSON Schema so clients know what inputs each tool accepts.

Error Handling

The add_note tool wraps logic in a try/catch and returns isError: true on failure. This tells the model the call failed instead of treating the response as a successful result.

Response Format

All tool handlers return MCP content blocks:

{
  content: [{ type: "text", text: "..." }]
}

In-Memory Storage

Notes are stored in a simple array inside the running process:

const notes: { title: string; content: string; ts: string }[] = [];

Notes are cleared when the server process restarts or the MCP client reloads the server.

Scripts

Command	Description
npm run build	Compile TypeScript to dist/
npm start	Run the compiled server
npm run dev	Build and run in one step

License

MIT