mcp-lab-01-notes-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-lab-01-notes-server list my pending tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-lab-01-notes-server
Nível 01 da trilha MCP Lab: primeiro servidor MCP construído com o SDK oficial (mcp no PyPI). Domínio: um gerenciador de notas e tarefas guardadas como arquivos markdown locais.
Termos técnicos seguem o glossário em ../CONTEXT.md.
O que este Server faz
5 Tools sobre uma pasta de arquivos .md:
Tool | O que faz |
| Cria uma nota; com |
| Lista todas as notas com título e status |
| Devolve o corpo completo de uma nota |
| Marca uma tarefa como concluída |
| Apaga uma nota |
flowchart LR
subgraph server.py [camada de protocolo]
T[Tools do MCPServer]
end
subgraph note.py [domínio]
N[Note, slugify, parse, render]
end
subgraph storage.py [armazenamento]
S[NotesStorage: ler/escrever/apagar .md]
end
T -->|delega| N
T -->|delega| S
N -.->|não conhece| S
S -.->|não conhece| Nserver.py é a única camada que conhece as duas outras. note.py (regra de negócio) e storage.py (arquivos) não se conhecem entre si — isso é proposital: dá pra trocar onde as notas são guardadas (um banco de dados, por exemplo) sem tocar no que é uma Nota.
Related MCP server: simple-mcp-example
Como rodar
uv sync
uv run pytest -q # 33 testes
uv run ruff check .
uv run mypyPor padrão as notas vão para ~/.mcp-lab/notes. Pra usar outra pasta:
NOTES_SERVER_DIR=/caminho/qualquer uv run notes-serverUsando de verdade no Claude Code
claude mcp add notes-server -- uv run --directory "$(pwd)" notes-serverDepois disso, numa conversa do Claude Code, peça pra ele criar uma nota ou listar suas tarefas — o modelo vai decidir sozinho quando chamar cada Tool.
Estrutura do código
src/notes_server/
├── storage.py → só sabe ler/escrever/apagar arquivos; barra path traversal
├── note.py → o que é uma Note; slugify; frontmatter -> Note e Note -> frontmatter
└── server.py → liga os Tools do MCP ao domínio; ToolError pros erros esperadosUm .md por camada em docs/, explicando o pra-quê/o-quê/como de cada uma:
O que este nível deliberadamente NÃO faz
Não expõe as notas como Resources nem tem Prompts prontos — isso é o Nível
02-resources-prompts.Não valida concorrência (dois processos escrevendo a mesma nota ao mesmo tempo) — fora de escopo pra um projeto local de estudo.
O frontmatter é um parser feito à mão, de propósito (ver
docs/02-dominio-nota.md) — não é um formato geral de YAML.
Referência oficial
modelcontextprotocol.io para a spec do protocolo. github.com/modelcontextprotocol/python-sdk para o código-fonte do SDK — o pacote mcp mudou de FastMCP para MCPServer na versão 2.x; se você ler isto muito depois, confira se a API ainda bate com o que está aqui.
Available Tools
5 toolscreate_noteA
Cria uma nova nota (ou tarefa pendente, se is_task=True).
Inputs: title (required), content, is_task. Returns: A forma "de fora" de uma Note: o que o modelo vê em list_notes/create_note.
delete_noteA
Apaga uma nota permanentemente pelo slug.
Inputs: slug (required). Returns: result
list_notesA
Lista todas as notas e tarefas salvas, com título e status.
Inputs: no named parameters. Returns: result
mark_doneB
Marca uma tarefa como concluída (status vira 'done').
Inputs: slug (required). Returns: A forma "de fora" de uma Note: o que o modelo vê em list_notes/create_note.
read_noteB
Lê o corpo completo de uma nota pelo slug.
Inputs: slug (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear primary action, and the CRUD operations are distinct. However, create_note doubles as a task creator via is_task, and mark_done applies only to tasks, which could cause slight ambiguity about whether notes also support status changes.
Most tools follow a clear verb_noun pattern (create_note, list_notes, read_note, delete_note), but mark_done breaks the pattern by using verb_adjective instead of verb_noun. This is a minor inconsistency that still leaves the intent understandable.
Five tools is appropriately scoped for a simple notes/tasks server. The set covers the essential operations without unnecessary bloat, making it easy for an agent to navigate.
The set lacks an update_note/edit_note operation, which is a notable gap for a notes domain. It also has no way to unmark a task or filter tasks from notes, limiting full lifecycle management for tasks.
Maintenance
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Create, list, and complete todo items through MCP.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables managing tasks in a structured TODO.md file through MCP tools for listing, adding, updating, setting status, logging notes, searching, and removing tasks while preserving hand-authored formatting.9 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables managing local Markdown notes by creating, viewing, listing, and searching notes and their contents through MCP tools.-
- AlicenseNot gradedqualityCmaintenanceEnables managing a local JSON notes file through five MCP tools: add, get, update, delete, and list notes, with atomic saves and a write lock.MIT
- AlicenseNot gradedqualityCmaintenanceEnables managing a local notes file through add, get, update, delete, and list operations via MCP.MIT