-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Feature: MCP Server Integration and Gemini Extension Support #488
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
StoyanD
wants to merge
28
commits into
Fission-AI:main
Choose a base branch
from
StoyanD:add_mcp
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
28 commits
Select commit
Hold shift + click to select a range
9d9c5d1
feat(gemini): add native extension support and unified prompts
StoyanD 4ed7faa
update the gemini doc to onboard user smoothly
StoyanD 7f8abeb
chore(openspec): archive gemini extension support change
StoyanD 001f285
Merge branch 'main' into gemini-extension
StoyanD 3318ed4
Merge branch 'main' into gemini-extension
StoyanD 2c3ca61
Merge branch 'main' into gemini-extension
StoyanD 85ac417
feat(openspec): add proposal for MCP server and .openspec migration
StoyanD 6785450
feat: implement mcp server and directory migration
StoyanD 80f74e8
docs: update tasks status
StoyanD 4e6b92e
test: update init tests to expect .openspec directory
StoyanD 31adee9
feat: complete mcp tools implementation and archive change
StoyanD 230a0d5
separate logic into core spec
StoyanD 4a5c901
fix(archive): handle errors gracefully and add spec update prompt
StoyanD 12fae4c
feat(release): sync gemini-extension.json version with package.json
StoyanD 84ebe16
docs: add MCP JSON configuration snippet to README
StoyanD 77a5b0b
feat(mcp): refactor core logic and expand MCP server tools
StoyanD 4eb0ba5
feat(mcp): complete MCP toolset parity
StoyanD 3bdf7cc
docs(openspec): archive refactor-core-isolation and update add-mcp-te…
StoyanD d068620
feat(core): refactor change logic and add MCP tests
StoyanD ad63aad
fix(lint): resolve restricted imports and ts-expect-error descriptions
StoyanD d4563c8
fix(mcp): resolve type errors in tools.ts
StoyanD b447e4d
refactor(mcp): decouple SpecCommand from mcp tools
StoyanD f1e2e96
archiving proposal
StoyanD a0958c5
chore: resolve merge conflicts and preserve CLI/MCP/Core separation r…
StoyanD 1dd5ecc
test: fix regressions in update.test.ts after merge resolution
StoyanD 95ed23b
feat: migrate to .openspec/ directory and implement security hardening
StoyanD 6e5150d
chore: update gemini extension to use direct mcp entry point
StoyanD afe3507
chore: use ${extensionPath} for MCP server resolution in gemini-exten…
StoyanD File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| # OpenSpec Extension for Gemini CLI | ||
|
|
||
| OpenSpec is an AI-native system for spec-driven development. It helps developers and AI agents maintain a shared understanding of project requirements and technical designs through a structured workflow. | ||
|
|
||
| This extension provides native integration via the Model Context Protocol (MCP), enabling a **zero-install workflow** where agents can manage OpenSpec without requiring the global `openspec` npm package. | ||
|
|
||
| ## MCP Capabilities | ||
|
|
||
| ### Tools | ||
| - `openspec_init`: Initialize or extend OpenSpec in the current project. | ||
| - `openspec_update`: Refresh instruction files and slash commands. | ||
| - `openspec_view`: Get dashboard data for specs and changes. | ||
| - `openspec_create_change`: Scaffold a new OpenSpec change directory. | ||
| - `openspec_list_changes`: List active change proposals. | ||
| - `openspec_list_specs`: List current specifications. | ||
| - `openspec_show_change`: Show details of a change (JSON/Markdown). | ||
| - `openspec_show_spec`: Show details of a specification (JSON/Markdown). | ||
| - `openspec_validate_change`: Validate a change proposal against schema rules. | ||
| - `openspec_archive_change`: Archive a completed change and update main specs. | ||
|
|
||
| ### Resources | ||
| - `openspec://changes/{name}/proposal`: Access the proposal.md content. | ||
| - `openspec://changes/{name}/tasks`: Access the tasks.md content. | ||
| - `openspec://specs/{id}`: Access the spec.md content for a capability. | ||
|
|
||
| ### Prompts | ||
| - `openspec_proposal`: Context and steps for scaffolding a new change. | ||
| - `openspec_apply`: Instructions for implementing an approved change. | ||
| - `openspec_archive`: Workflow for archiving a completed change. | ||
|
|
||
| ## Zero-Install Usage | ||
|
|
||
| If you have this extension added to your Gemini CLI, you can start using OpenSpec immediately in any directory by asking: | ||
|
|
||
| > "Initialize OpenSpec in this project" | ||
|
|
||
| The agent will use `openspec_init` to scaffold the necessary files. No local or global installation of `@fission-ai/openspec` is required for AI-driven workflows. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| This extension requires the Gemini CLI. The OpenSpec MCP server is bundled with the extension. | ||
|
|
||
| **Auto-Initialization Instruction**: | ||
| When the user starts a session or tries to use OpenSpec: | ||
| 1. **Check for CLI**: Run `openspec --version`. | ||
| - If found, use `openspec` for all commands. | ||
| - If missing, prefer using the bundled MCP server tools or fall back to `npx` (or `pnpm dlx`): | ||
| ```bash | ||
| npx "@fission-ai/openspec" | ||
| ``` | ||
| - Inform the user if a global installation is recommended for performance, but do not perform it automatically. | ||
| 2. **Check for Slash Commands**: Verify if `.gemini/commands/openspec/` exists and contains `proposal.toml`, `apply.toml`, and `archive.toml`. | ||
| - If missing, **automatically generate them** using the logic defined in the "Maintenance: Slash Command Synchronization" section below. | ||
| - Inform the user: "OpenSpec slash commands have been generated. You may need to restart the CLI to see them." | ||
| 3. **Check for Project Initialization**: Verify if the `.openspec/` directory exists in the project root (or legacy `openspec/`). | ||
| - If missing, automatically run `openspec init` to scaffold the project structure. | ||
| 4. **Populate Project Context**: | ||
| - **Trigger**: When `openspec init` completes and suggests "Populate your project context", you MUST perform this immediately. | ||
| - **Action**: Read `.openspec/project.md`, analyze project config (`package.json`, etc.), and fill in the details. **Do not** ask the user to do this manually. | ||
|
|
||
| ## Core Mandates for Gemini Agents | ||
|
|
||
| - **Specs are Truth**: Always read `.openspec/specs/` to understand the current state of a capability. | ||
| - **Changes are Proposals**: All modifications to behavior or requirements MUST start as a proposal in `.openspec/changes/`. | ||
| - **Minimize Confirmations**: Do not ask for permission for low-risk read operations or standard project scaffolding if the user's intent is clear. Assume consent for actions explicitly requested. | ||
| - **Three-Stage Workflow**: | ||
| 1. **Stage 1: Creating Changes**: Scaffold `proposal.md`, `tasks.md`, and spec deltas. Validate with `openspec validate <id> --strict`. | ||
| 2. **Stage 2: Implementing Changes**: Follow `tasks.md` sequentially. | ||
| 3. **Stage 3: Archiving Changes**: Move completed changes to `archive/` using `openspec archive <id>`. | ||
|
|
||
| ## Essential CLI Commands | ||
|
|
||
| When working in an OpenSpec-enabled project, you can use these commands: | ||
|
|
||
| - `openspec list`: Show active changes. | ||
| - `openspec list --specs`: Show existing capabilities. | ||
| - `openspec show <id>`: View details of a change or spec. | ||
| - `openspec validate <id>`: Validate a change against the project's specs. | ||
| - `openspec init`: Initialize OpenSpec in a new project. | ||
| - `openspec update`: Update instruction files (like `AGENTS.md`). | ||
|
|
||
| ## Directory Structure | ||
|
|
||
| - `.openspec/project.md`: Project-specific conventions and tech stack. | ||
| - `.openspec/specs/`: Current requirements and scenarios (the "truth"). | ||
| - `.openspec/changes/`: Pending proposals and implementation tasks. | ||
|
|
||
| ## Writing Specs | ||
|
|
||
| Requirements must be normative (SHALL/MUST). Every requirement MUST have at least one scenario using the following format: | ||
|
|
||
| ```markdown | ||
| #### Scenario: Name | ||
| - **WHEN** action or condition | ||
| - **THEN** expected result | ||
| ``` | ||
|
|
||
| For more detailed instructions, refer to `.openspec/AGENTS.md`. | ||
|
|
||
| ## Maintenance: Slash Command Synchronization | ||
|
|
||
| The slash commands for this extension (`.gemini/commands/openspec/*.toml`) are generated artifacts. The single source of truth for their content is `src/core/templates/prompts.ts`. | ||
|
|
||
| **Instruction**: When `src/core/templates/prompts.ts` is modified, or when asked to "update slash commands", you MUST regenerate the TOML files in `.gemini/commands/openspec/` using the following logic: | ||
|
|
||
| 1. **Read** `src/core/templates/prompts.ts` to extract the exported constants. | ||
| 2. **Construct** the prompt body for each command by joining the relevant constants with `\n\n`: | ||
| - **proposal**: `PROPOSAL_GUARDRAILS` + `PROPOSAL_STEPS` + `PROPOSAL_REFERENCES` | ||
| - **apply**: `BASE_GUARDRAILS` + `APPLY_STEPS` + `APPLY_REFERENCES` | ||
| - **archive**: `BASE_GUARDRAILS` + `ARCHIVE_STEPS` + `ARCHIVE_REFERENCES` | ||
| 3. **Generate** the TOML files with the following structure (preserving the `<!-- OPENSPEC:START -->` markers inside the prompt string): | ||
|
|
||
| **File**: `.gemini/commands/openspec/proposal.toml` | ||
| ```toml | ||
| description = "Scaffold a new OpenSpec change and validate strictly." | ||
| prompt = """ | ||
| <!-- OPENSPEC:START --> | ||
| {PROPOSAL_BODY} | ||
| <!-- OPENSPEC:END --> | ||
| """ | ||
| ``` | ||
|
|
||
| **File**: `.gemini/commands/openspec/apply.toml` | ||
| ```toml | ||
| description = "Implement an approved OpenSpec change and keep tasks in sync." | ||
| prompt = """ | ||
| <!-- OPENSPEC:START --> | ||
| {APPLY_BODY} | ||
| <!-- OPENSPEC:END --> | ||
| """ | ||
| ``` | ||
|
|
||
| **File**: `.gemini/commands/openspec/archive.toml` | ||
| ```toml | ||
| description = "Archive a deployed OpenSpec change and update specs." | ||
| prompt = """ | ||
| <!-- OPENSPEC:START --> | ||
| {ARCHIVE_BODY} | ||
| <!-- OPENSPEC:END --> | ||
| """ | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| { | ||
| "name": "openspec", | ||
| "version": "0.19.0", | ||
| "contextFileName": "GEMINI.md", | ||
| "mcpServers": { | ||
| "openspec": { | ||
| "command": "node", | ||
| "args": [ | ||
| "${extensionPath}/dist/mcp/index.js" | ||
| ] | ||
| } | ||
| } | ||
| } |
15 changes: 15 additions & 0 deletions
15
openspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # Add Gemini CLI Extension Support | ||
|
|
||
| ## Why | ||
| Integrating with Gemini CLI makes agents “OpenSpec-aware” by default, reducing setup friction and improving correctness via project-specific context. | ||
|
|
||
| ## What Changes | ||
| - Add `gemini-extension.json` extension manifest (non-breaking). | ||
| - Add `GEMINI.md` Gemini-focused usage/context doc (non-breaking). | ||
| - Extract shared prompts into `src/core/templates/prompts.ts` (non-breaking). | ||
| - Add native Gemini slash commands under `.gemini/commands/openspec/` (non-breaking). | ||
|
|
||
| ## Impact | ||
| - **Specs**: N/A (no spec schema changes). | ||
| - **Code**: New extension metadata + prompt source-of-truth; Gemini CLI users get a first-class onboarding path. | ||
|
|
8 changes: 8 additions & 0 deletions
8
.../changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| ## ADDED Requirements | ||
| ### Requirement: Slash Command Safety | ||
| All generated slash command templates SHALL include safety guardrails. | ||
|
|
||
| #### Scenario: CLI Availability Check | ||
| - **WHEN** generating slash commands for any tool | ||
| - **THEN** the template SHALL include an instruction to verify the `openspec` CLI is installed and available in the environment | ||
| - **AND** guide the user to install it via `npm install -g @fission-ai/openspec` if missing |
8 changes: 8 additions & 0 deletions
8
openspec/changes/archive/2025-12-21-add-gemini-extension-support/tasks.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| - [x] Create `gemini-extension.json` in the project root @file:gemini-extension.json | ||
| - [x] Create `GEMINI.md` in the project root with OpenSpec context @file:GEMINI.md | ||
| - [x] Extract slash command prompts to a shared location for unified usage across agents | ||
| - [x] Configure `GEMINI.md` to auto-generate slash commands from shared prompts | ||
| - [x] Document CLI installation prerequisites in `GEMINI.md` and shared prompts | ||
| - [x] Add maintenance instructions to `GEMINI.md` for syncing slash commands from `prompts.ts` | ||
| - [x] Update `README.md` with Gemini CLI Extension installation and benefits | ||
| - [x] Verify the extension can be linked locally using `gemini extensions link .` (Manual verification) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.