This is a submission for the Notion MCP Challenge
What I Built
Spec Hub for Notion is a full-featured engineering specification management system that turns your Notion workspace into a structured, AI-programmable spec tracking platform. It exposes 20 MCP tools that let any AI assistant (Claude, Cursor, VS Code Copilot) manage the entire lifecycle of engineering specs through natural language.
The system solves a real pain point I've experienced on engineering teams: specs scattered across Google Docs, Confluence, and Slack threads, with no traceability between changes, decisions, and bugs. Spec Hub centralizes everything into 6 interconnected Notion databases with full relational integrity.
Key Capabilities
- One-command workspace setup — Creates 6 fully-configured Notion databases (Projects, Spec Items, Spec Versions, Change Requests, Decision Logs, Bugs) with proper schemas, relations, select options, and cross-references
- Spec lifecycle management — Create specs, version them with automatic versioning (v1, v2...), approve/deprecate versions, and track status through defined workflows
- Change request board — File change requests against specs with priority levels, impact assessment, and kanban-style status tracking
- Bug filing with @mentions — File bugs linked to specs, and the system automatically @mentions the assignee in a Notion comment so they get a native notification
- Decision logging — Record architectural decisions with rationale and link them to specific specs and change requests for full traceability
- Impact linking — Bidirectional impact links between any two database entries via Notion comments, creating a traceability graph
-
Risk dashboard —
get_overviewcomputes risk flags across your workspace: specs stuck in review, high-severity open bugs, stalled change requests - Timeline view — Merges events from all 6 databases into a single chronological feed, so you can see everything that happened to a spec
The 20 Tools
| Category | Tools |
|---|---|
| Setup | setup_workspace |
| Projects |
create_project, list_projects
|
| Specs |
create_spec, list_specs, get_spec
|
| Versions |
create_version, approve_version
|
| Change Requests |
create_cr, list_crs, update_cr
|
| Decisions | log_decision |
| Bugs |
file_bug, list_bugs, update_bug
|
| Analytics |
get_overview, get_timeline
|
| Utility |
search, list_users, impact_link
|
Video Demo
Here's how Spec Hub works in practice — from workspace setup to spec creation, bug filing with @mentions, and analytics:
Workflow example with Claude:
User: "Set up Spec Hub in my Notion workspace"
→ Creates 6 databases with schemas, relations, and select options
User: "Create a KPI spec called deposition_stability_score in the Neuro Dashboard project, owned by Alice"
→ Creates spec + auto-generates v1
User: "File a critical bug: stability score returns NaN when input has <5 data points. Assign to Bob."
→ Creates bug entry + @mentions Bob in Notion comment → Bob gets notified instantly
User: "Show me the project overview"
→ Returns risk dashboard with open bugs, stalled CRs, specs needing review
Show us the code
SissiFeng
/
spec-hub-notion
Engineering Spec Management System powered by Notion MCP — track specs, change requests, decisions, and bugs in Notion with full traceability and @mention support. Built for the Notion MCP Challenge.
Spec Hub for Notion
Engineering Spec Management System powered by Notion MCP — track specs, change requests, decisions, and bugs in Notion with full traceability, @mention support, and cross-linking.
Built for the Notion MCP Challenge.
What It Does
Spec Hub turns your Notion workspace into a structured engineering specification management system. It bridges the gap between internal engineering teams and external collaborators by providing:
- Structured Spec Registry — Versioned specs (KPIs, API contracts, components, parameters, etc.) with JSON content, diff-ready history, and approval workflows
-
Change Request Board — Kanban-style workflow tracking from
proposed → under_review → approved → implementing → verified → closed, with impact flags showing which teams need to sync - Decision Logs — Immutable records of why decisions were made, with alternatives considered and participants recorded
- Bug Tracking with @Mentions — File bugs linked to specs, auto-mention assignees in Notion comments so they get notified immediately
- …
Architecture:
AI Assistant (Claude / Cursor / VS Code)
│
│ MCP Protocol (stdio)
▼
spec_hub_notion (FastMCP Server)
├─ 20 registered tools
├─ Pydantic v2 input validation
├─ Async NotionClient (httpx)
│
│ Notion REST API v1
▼
Notion Workspace
├─ Projects DB
├─ Spec Items DB ←─ relations ─→ Spec Versions DB
├─ Change Requests DB
├─ Decision Logs DB
└─ Bugs DB
Tech stack: Python 3.10+, FastMCP (MCP SDK), Pydantic v2, httpx (async), Notion API v1
How I Used Notion MCP
Spec Hub makes deep use of 7 Notion API endpoints through a custom async client, going well beyond basic CRUD:
1. Database Creation with Rich Schemas
The setup_workspace tool programmatically creates 6 databases with complex schemas including select/multi-select options, relation properties linking databases together, and rich text fields. Each database is created with pre-configured select options (e.g., spec types: kpi, component, api_contract, data_pipeline; bug severities: critical, high, medium, low).
2. Relational Data Model
Specs, versions, change requests, and bugs are all interconnected through Notion relation properties. When you create a spec, it auto-generates a linked version entry. When you file a bug, it links to the affected spec. This creates a queryable dependency graph inside Notion.
3. @Mention Notifications via Comments API
The killer feature: when filing a bug, Spec Hub uses the Notion Comments API to post a comment with a user @mention (using the mention_user() rich text block). This triggers a native Notion notification to the assignee — no external integration needed. The system resolves user IDs via the Users API, so you can assign bugs by name.
4. Bidirectional Impact Links
The impact_link tool creates traceability between any two entries (e.g., linking a bug to a change request) by posting reciprocal comments on both pages. This creates a navigable audit trail inside Notion itself.
5. Computed Analytics from Database Queries
The get_overview tool queries all 6 databases and computes aggregate risk metrics: how many specs are stuck in review, how many critical bugs are open, which change requests have stalled. It returns a structured dashboard that an AI assistant can reason about.
6. Cross-Database Timeline
The get_timeline tool merges created_time and last_edited_time from entries across all databases into a single chronological feed. This gives teams a unified activity log — something Notion doesn't natively provide across databases.
7. Full-Text Search
The search tool wraps Notion's search API to find specs, bugs, or decisions by keyword across the entire workspace.
What This Unlocks
By exposing these capabilities through MCP, any AI assistant becomes a spec management co-pilot. Engineers can:
- Create and version specs through natural conversation
- File bugs and automatically notify the right person
- Get a risk assessment of their project in one question
- Trace any change back to the decision and spec that motivated it
The Notion workspace becomes both the source of truth and the collaboration surface — humans work in Notion's UI, AI works through MCP, and everything stays in sync.
Built with Python, FastMCP, and the Notion API. MIT licensed.
Top comments (1)
WOW