microscope MCP

Add microscope capabilities to claude code, codex, copilot, ... as spec driven development provider.

Exposed tools

The MCP server exposes 86 tools across four modules.

Strategy

Tool	Description
GetOkr	Get the list of OKR (Objective Key Results) in the system
GetOkrById	Get an OKR by its identifier
GetPublishedOkrs	Get the list of published OKRs in the system
CreateOkr	Create an OKR in the system
UpdateOkr	Update an existing OKR in the system
DeleteOkr	Delete an OKR from the system
ToggleOkrPublished	Toggle the published state of an OKR in the system
AddKeyResult	Add a Key Result to an existing OKR in the system
UpdateKeyResult	Update a Key Result belonging to an OKR in the system
DeleteKeyResult	Delete a Key Result from an existing OKR in the system
GetStrategicInitiatives	Get the list of strategic initiatives in the system
GetStrategicInitiativeById	Get a strategic initiative by its identifier
CreateStrategicInitiative	Create a new strategic initiative in the system
UpdateStrategicInitiative	Update an existing strategic initiative in the system
UpdateStrategicInitiativeMetadata	Update strategic initiative metadata in the system
DeleteStrategicInitiative	Delete an existing strategic initiative in the system
AddStrategicInitiativeActionPlanItem	Add an action plan item to a strategic initiative
UpdateStrategicInitiativeActionPlanItem	Update an action plan item belonging to a strategic initiative
RemoveStrategicInitiativeActionPlanItem	Remove an action plan item from a strategic initiative
SetStrategicInitiativeActionPlanItemStatus	Set the status of an action plan item belonging to a strategic initiative
AddTagToStrategicInitiativeActionPlanItem	Add a tag to an action plan item belonging to a strategic initiative
RemoveTagFromStrategicInitiativeActionPlanItem	Remove a tag from an action plan item belonging to a strategic initiative
AddStrategicInitiativeGovernanceInstance	Add a governance instance to a strategic initiative
UpdateStrategicInitiativeGovernanceInstance	Update a governance instance belonging to a strategic initiative
UpdateStrategicInitiativeGovernanceInstanceMetadata	Update governance instance metadata in the system
RemoveStrategicInitiativeGovernanceInstance	Remove a governance instance from a strategic initiative
GetGovernanceInstanceById	Get a governance instance by strategic initiative identifier and governance instance identifier
GetPortfolioKpi	Get the portfolio KPIs (aggregated metrics) in the system

Product

Tool	Description
GetPrds	Get the list of PRDs in the system
GetPrdById	Get a PRD by its identifier
CreatePrd	Create a new PRD
UpdatePrd	Update an existing PRD
UpdatePrdMetadata	Update metadata of an existing PRD
DeletePrd	Delete a PRD in the system
GetIssues	Get the list of Issues (bugs and business problems) in the system
GetIssueById	Get an Issue by its identifier
CreateIssue	Create a new Issue (bug or business problem) to manage the run, with its full initial state
UpdateIssue	Update an existing Issue title and content
UpdateIssueMetadata	Update metadata of an existing Issue: type, linked PRD/Workload/ServiceIncident, lifecycle dates and status
DeleteIssue	Delete an Issue in the system
GetProductKpi	Get the product KPIs (aggregated PRD metrics) in the system

Tech

Tool	Description
GetWorkloads	Get the list of workloads in the system
GetWorkloadById	Get a workload by its identifier
CreateWorkload	Create a new workload in the system
UpdateWorkload	Update an existing workload in the system
DeleteWorkload	Delete an existing workload in the system
AddComponent	Add a component to a workload in the system
UpdateComponent	Update a component belonging to a workload in the system
DeleteComponent	Delete a component from a workload in the system
AddDependency	Add a dependency between workloads in the system
RemoveDependency	Remove a dependency between workloads in the system
GetServiceIncidents	Get the list of service incidents in the system
GetServiceIncidentById	Get a service incident by its identifier
CreateServiceIncident	Create a new service incident in the system
UpdateServiceIncident	Update a service incident content in the system
UpdateServiceIncidentMetadata	Update service incident metadata in the system
DeleteServiceIncident	Delete a service incident from the system
GetTechKpi	Get technical KPIs (MTBF and MTTR) across workloads

Experience

Tool	Description
GetPersonae	List all personae
GetPersonaById	Get a persona by its identifier
CreatePersona	Create a new persona
UpdatePersona	Update an existing persona's title and content
UpdatePersonaMetadata	Update an existing persona's metadata (type)
DeletePersona	Delete a persona by its identifier
GetJourneys	List all customer/user journeys
GetJourneyById	Get a journey by its identifier, including its steps, pain points and opportunities
CreateJourney	Create a new customer/user journey
UpdateJourney	Update a journey's title, description and experience health scores (CSAT, CES, NPS)
DeleteJourney	Delete a journey by its identifier
AddJourneyStep	Add a step to a journey and return the new step identifier
UpdateJourneyStep	Update a step of a journey
RemoveJourneyStep	Remove a step from a journey
AddPainPointToStep	Add a pain point to a journey step
RemovePainPointFromStep	Remove a pain point from a journey step
ToggleResolvePainPoint	Resolve or reopen a pain point on a journey step
AddOpportunityToStep	Add an opportunity to a journey step
RemoveOpportunityFromStep	Remove an opportunity from a journey step
LinkPersonaToStep	Link a persona to a journey step
UnlinkPersonaFromStep	Unlink the persona from a journey step
LinkWorkloadToStep	Link a workload to a journey step
UnlinkWorkloadFromStep	Unlink the workload from a journey step

Settings

Tool	Description
GetTemplates	Get the list of content templates in the system
GetTemplateById	Get a content template by its identifier
CreateTemplate	Create a new content template in the system
UpdateTemplate	Update an existing content template in the system
DeleteTemplate	Delete an existing content template in the system

Un modèle cible un seul type d'agrégat — Prd, Issue, StrategicInitiative, ServiceIncident, Workload, Persona ou DocumentationPage — et porte son propre type d'éditeur (Block, Markdown ou RichText). Lisez un modèle avant de rédiger du contenu pour respecter la structure propre à l'organisation.

---

Add MCP

Add microscope MCP to project .mcp.json:

{
  "mcpServers": {
    "microscope": {
      "type": "http",
      "url": "http://localhost:5095/mcp",
      "oauth": {
        "clientId": "microscope-mcp-client"
      }
    }
  }
}

Add Skill: PRD → backlog

mkdir .claude/skills/mcsp-specify
touch .claude/skills/mcsp-specify/SKILL.md

Then copy in .claude/skills/mcsp-specify/SKILL.md this content :

```markdown
---
name: mcsp-specify
description: >-
Turn a Product Requirement Document (PRD) into an implementation-ready US/TS
spec, then build it. Fetch the PRD from the Microscope MCP server, brainstorm
its decomposition into User Stories and Technical Stories WITH the user, write
the result as an iterable markdown spec under .microscope/specs/{prd_name}/, and
once the user validates that spec, start implementing the stories in order.
Use this skill WHENEVER the user mentions a PRD, decomposing / slicing / breaking
down a feature or initiative, a backlog of user or technical stories, "from
Microscope" or the Microscope MCP server, or wants to go from a product spec to
code in this repo — even if they don't say "skill" or name every step. Code
conventions are NOT here: follow the repo's CLAUDE.md rules when implementing.
---

# Microscope: PRD → US/TS spec → implementation

This skill owns the path **spec → sign-off → code**:

1. **Fetch** the PRD (and its context) from the **Microscope MCP server**.
2. **Brainstorm** the decomposition into **User Stories (US)** and **Technical Stories (TS)** with the user.
3. **Write** it as a living markdown spec at `.microscope/specs/{prd_name}/spec.md` that the user iterates on.
4. On **validation**, **implement** the stories in the agreed order, updating the spec's status as you go.

The spec file is the contract between brainstorming and coding. Never start implementing before the user has validated it. **This skill does not define code conventions** — architecture, slicing, and coding rules live in the repo's `CLAUDE.md`; read and follow those during implementation.

---

## Phase 0 — Connect to Microscope (brief)

Confirm a **Microscope MCP server** is connected and list its tools. If it isn't, tell the user how to enable it and stop. The PRD is fetched with the **`GetPrdById`** tool.

---

## Phase 1 — Fetch the PRD + context via MCP

Get the target PRD by calling **`GetPrdById`** with the PRD's id. If the user didn't give an id, list the candidate PRDs (via the relevant MCP read tool) and ask which to work on, then call `GetPrdById`.

Pull the context that keeps the spec traceable, since a PRD never stands alone:
- the **workloads / components** likely impacted by the PRD's implementation (for traceability and to flag potential cross-cutting concerns early)

Restate the PRD back to the user in your own words — goal, persona(s), problem, in/out of scope, success metrics, constraints/NFRs — and flag gaps or contradictions before slicing. An ambiguous PRD makes a bad spec.

---

## Phase 2 — Brainstorm the decomposition (with the user)

Decompose top-down, keeping the codebase's ubiquitous language:

 ─ PRD
     ├─ US  (As a <persona>, I want <capability>, so that <benefit>)
     └─ TS  (technical enabler: schema, refactor, GraphQL, security, perf, observability…)

Guidance to apply while slicing:
- **US** get **Gherkin acceptance criteria** (Given/When/Then) with at least one edge/negative case.
- **TS** state the technical outcome *and why it unblocks user value* — enablers only, no speculative gold-plating.
- Run each story through **INVEST**; if it fails, re-slice.
- Slice **vertically** (a story cuts through all layers and is shippable/testable on its own), not horizontally. Start with a **walking skeleton** — the thinnest end-to-end path.
- Note per story: rough **size/effort**, a **WSJF/RICE** signal consistent with the Product priority matrix, **dependencies**, **risks/assumptions**.
- Propose a **sequence**: walking skeleton → highest priority → dependents.

This is dialogue, not monologue — propose, then let the user push back. The output of this phase goes straight into the spec file.

---

## Phase 3 — Write & iterate the spec file

Create `.microscope/specs/{prd_name}/spec.md`, where `{prd_name}` is a slug of the PRD title/id (lowercase, hyphenated). Create the folders if missing. If a spec already exists for this PRD, open it and iterate on it rather than overwriting.

Use this structure exactly:

---
prd: <PRD id or title>
prd_source: microscope-mcp
status: draft        # draft | validated | in-progress | done
updated: <YYYY-MM-DD>
---

# Spec — <PRD title>

## 1. Context
Goal, target persona(s), problem, in-scope / out-of-scope, success metrics, constraints & NFRs.

## 2. Decomposition
- **[US-1]** As a <persona>, I want <capability>, so that <benefit>.
  - **AC:** Given … When … Then … (+ edge case)
  - size: S/M/L · WSJF: <n> · depends on: — · status: todo
- **[TS-1]** <technical outcome> — unblocks <US/feature>.
  - size: S · depends on: — · status: todo

### Feature B — <name>
…

## 4. Sequence
Ordered list of story IDs (walking skeleton first), with rationale.

## 5. Open questions / risks

Then ask the user to review: reprioritize, cut scope, edit ACs. Update the file on each round and bump `updated`. Keep `status: draft` until they explicitly approve.

**Validation gate:** treat the spec as validated only when the user clearly approves (in chat) or sets `status: validated` in the file. Until then, do not write production code.

---

## Phase 4 — Implement the validated spec

Once validated, set `status: in-progress`, then implement the stories **in the sequence from §4**, one vertical slice at a time, foundational/walking-skeleton first.

- **Follow `CLAUDE.md`.** All architecture, vertical-slice/CQRS patterns, persistence, testing, I18N and frontend conventions live there — read the relevant rules and mirror existing code. Do not invent conventions here.
- After each story: build + tests green, then mark its `status: done` in the spec and reference the story ID (e.g. `US-1`) in the commit message.
- Keep diffs reviewable — one slice per logical commit. Don't touch unrelated code unless a TS explicitly calls for it.
- When every story is `done`, set the spec `status: done`. If the user wants the backlog reflected back in Microscope, offer to write it via MCP (mirroring the bounded-context commands), respecting MCP guardrails.

---

## Guardrails
- Discover MCP tool names — never hardcode guesses.
- The spec file is the single source of truth between brainstorm and code; keep it current.
- No production code before the validation gate.
- Conventions belong to `CLAUDE.md`, not to this skill.
- If the PRD is too thin to slice responsibly, say so and ask for the missing pieces instead of inventing requirements.

Start Spec Driven Development

Start claude code session for your project and ask :

"Start the specification of the PRD with id : {your_prd_id}"

Or just :

/mcsp-specify