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

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:

{
  "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

License

MIT