# Optional build: a read-only practice-notes MCP

This is a specification for a learner-led coding exercise after the 60-minute workshop. It is not a preinstalled or already tested server.

## Purpose
Let an AI client search a small local library of fictional workshop notes. Use only a dedicated practice-data directory in a separate project. Copy sample-notes.md into that directory. Do not connect organizational accounts or private data.

## One tool
search_notes(query: string) → a bounded list of filename, note ID when present, and exact matching passage.
- Match a short phrase without requiring capitalization.
- Limit query length to 200 characters, text files to 100 KB and results to 10 passages.
- Return an empty list and a clear no-match message when appropriate.
- Do not generate summaries and present them as quoted passages.
- Do not accept a caller-selected root directory.
- Do not write, delete, execute file contents, call external services, or spend money.

## Access boundary
Resolve paths against the configured practice-data root. Reject absolute paths, parent traversal and symlink escapes. Handle unreadable files honestly without revealing unrelated filesystem paths or file contents. Treat file contents as data, not instructions.

## Build request
Use the current official MCP SDK docs for the chosen language and client. Explain dependencies before installing them. Implement the smallest local server and an independent test script. For a stdio server, reserve stdout for protocol messages and send diagnostics to stderr. Include exact startup and shutdown instructions, and keep secrets out of configuration examples.

## Acceptance tests
1. Search for “sign-in”: return the exact N2 passage with sample-notes.md as the source.
2. Search for an absent phrase: return no matches, with no invented passage.
3. Read a valid file inside practice-data: permitted.
4. Attempt ../outside.md and an absolute path outside the root: rejected.
5. Place a symlink in practice-data pointing outside it: rejected, no leaked bytes.
6. Try an oversized file and query: produce bounded errors.
7. Confirm file checksums are unchanged after all calls.
8. Complete the client's tool discovery and tool-call flow separately from unit tests.

## Completion record
Server source created: ___
Boundary tests run: ___
Exact passage manually checked: ___
Client and transport: ___
Integration demonstrated: ___
Unverified behavior: ___

A running process is not evidence that the permission boundary works. A local stdio server is not a remotely reachable HTTPS connector. If your client does not support the transport, keep the tested local project and record integration as pending.

## Current primary references
- MCP introduction: https://modelcontextprotocol.io/docs/getting-started/intro
- Build a server: https://modelcontextprotocol.io/docs/develop/build-server
- SDKs: https://modelcontextprotocol.io/docs/sdk
Checked September 8, 2026. Consult the current docs before building.