Spec Hub for Notion: 20-Tool MCP Server for Engineering Spec Management

Sissi Feng — Sat, 28 Mar 2026 20:10:14 +0000

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_overview computes 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
…

View on GitHub

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.

DEV Community: Sissi Feng