# MCPipe Toolchain

MCPipe Toolchain exposes company knowledge to AI clients through read-only tools for Confluence, GitHub, Jira, Figma, Outlook, Teams, and browser automation. It is designed for safe discovery, retrieval, and summarization of internal information without modifying source systems.

## What these servers are

The MCP server is a local bridge between AI clients (like VS Code Copilot) and enterprise systems. It provides a consistent tool surface across:

- Confluence for documentation search and page retrieval
- GitHub for repository discovery, code search, and file access
- Jira for issue lookup, sprint visibility, and project metadata
- Figma for file metadata, nodes, comments, components, styles, and exports
- Microsoft 365 Outlook and Teams for read-only messaging and calendar context
- Browser automation for localhost tab interaction, diagnostics, and React inspection

An optional Electron desktop app hosts provider configuration and starts the MCP HTTP endpoint.

## Tools available

### Unified read-only tools

- `search` to query Jira and Confluence in one call
- `fetch` to retrieve a Jira issue or Confluence page by resource URI

### Confluence tools

- `search_confluence` for keyword search across pages
- `get_confluence_page` to fetch a page by ID (with chunking)
- `search_confluence_cql` for advanced CQL queries
- `get_confluence_spaces` to list accessible spaces
- `get_confluence_page_children` to navigate page trees
- `get_confluence_page_labels` to list labels/tags
- `get_confluence_page_attachments` to list attachments
- `get_confluence_page_by_title` to fetch a page by title in a space
- `get_confluence_page_comments` to fetch comments
- `get_confluence_page_inline_comments` to fetch inline comments
- `get_confluence_page_footer_comments` to fetch footer comments
- `get_confluence_comment_children` to fetch reply (child) comments
- `get_confluence_page_descendants` to fetch descendant pages
- `get_confluence_pages_in_space` to list pages in a space

### GitHub tools

- `search_github_code` for organization-wide code search
- `get_github_file` to fetch file content (with optional line range)
- `search_github_paths` to discover file or directory paths inside a repo
- `list_github_repo_tree` to browse remote repo structure without a local clone
- `list_github_repos` to page through repositories
- `search_github_repos` to find repos by name/topic/language
- `get_github_pull_requests` and `get_pull_request_details`
- `get_github_issues` for issue lists
- `get_github_commits` and `get_github_commit` for history and diffs
- `get_github_branches` and `get_github_repo_info`

### Jira tools

- `search_jira_issues` for text search
- `search_jira_jql` for advanced JQL queries
- `get_jira_issue`, `get_jira_issue_basic`, `get_jira_issue_common`, `get_jira_issue_full`
- `get_jira_projects`, `get_jira_issue_types`, `get_jira_statuses`
- `get_jira_issue_comments`, `get_jira_issue_changelog`
- `get_jira_issue_transitions`, `get_jira_issue_watchers`
- `get_jira_issue_remote_links` to list remote links
- `get_jira_issue_type_meta_with_fields` to fetch issue field metadata
- `get_jira_project_issue_types_metadata` to fetch project issue type metadata
- `atlassian_user_info` to fetch the current user
- `lookup_jira_account_id` to search for user account IDs
- `get_jira_boards`, `get_jira_sprints`, `get_jira_sprint_details`
- `get_jira_sprint_issues`, `get_jira_sprint_report`
- `get_jira_epic_stories`, `get_jira_issue_children`

### Figma tools

- `get_figma_file`, `get_figma_node`
- `get_figma_comments`, `get_figma_versions`
- `get_figma_components`, `get_figma_component`, `get_figma_styles`
- `get_figma_dev_resources`, `get_figma_images`
- `get_figma_projects`, `get_figma_project_files`
- `get_figma_team_components`, `get_figma_team_styles`

### Microsoft 365 tools

- Outlook: `search_outlook_emails`, `get_outlook_email`, `get_outlook_calendar_events`
- Teams: `get_teams_joined_teams`, `get_teams_channels`, `get_teams_channel_messages`
- Teams: `search_teams_messages`, `get_teams_chats`, `get_teams_chat_messages`

### Browser and React tools

- Browser control and diagnostics: `browser_list_tabs`, `browser_attach_tab`, `browser_navigate`, `browser_wait`, `browser_wait_for`
- Browser inspection: `browser_get_dom`, `browser_get_page_state`, `browser_get_text`, `browser_get_element_value`, `browser_get_count`
- Browser visuals and reports: `browser_screenshot`, `browser_full_page_screenshot`, `browser_generate_report`
- Browser styling/debug: `browser_get_computed_styles`, `browser_get_box_model`, `browser_get_console`, `browser_get_network_failures`
- Browser interactions: `browser_click`, `browser_click_text`, `browser_click_role`, `browser_type`, `browser_set_value`
- JavaScript fallback and usage helper: `browser_run_script`, `browser_get_tool_usage`
- Browser orchestration checks: `browser_compare_figma_styles`, `browser_verify_user_intent`
- React inspection: `browser_find_by_component_name`, `browser_find_by_label`, `browser_get_component_props`, `browser_get_component_state`, `browser_detect_hydration_issues`, `browser_get_diagnostics`

### Browser backend modes

Browser tools can run with one of three backends:

- `extension` (default): current Browser MCP Extension bridge
- `playwright`: managed Playwright Chromium session (no extension)
- `cdp`: attach Playwright to an existing Chrome via CDP (no extension)

Configure in `config.json` (or with env vars):

- `browserBackend`: `extension` | `playwright` | `cdp`
- `browserHeadless`: `true`/`false` (Playwright mode)
- `browserChannel`: optional browser channel for Playwright launch
- `browserCdpUrl`: CDP endpoint URL (default `http://127.0.0.1:9222`)

Environment variable overrides:

- `BROWSER_BACKEND`
- `BROWSER_HEADLESS`
- `BROWSER_CHANNEL`
- `BROWSER_CDP_URL`

Notes:

- Localhost-only navigation is enforced (`localhost` and `127.0.0.1`).
- React helper diagnostics remain extension-only in this version.

## How our toolchain compares to out-of-the-box MCP servers

Vendors ship their own MCP servers — the official Atlassian Remote MCP, the Datadog MCP, and the Figma Dev Mode MCP. They work, but each was built to expose *one* product. This toolchain is built for how engineers and AI clients actually work: across systems, safely, and with a tool surface that doesn't drown the model in schemas.

Three design choices make ours better and more flexible than the stock servers:

1. **One intent-first tool per provider, not dozens of schemas.** Each provider exposes a single tool (`jira`, `confluence`, `github`, `datadog`, `figma`, `m365`, `browser`) that takes a free-text `intent`. The tool internally routes to the right operation using semantic search over handler descriptions, then fills parameters with per-system extractors. The model sees ~7 tools instead of ~120, so context stays small and tool selection stays accurate. Stock servers register every operation as its own tool schema, all of which load into context every session and compete during selection (the classic `getIssue` vs `getIssueFull` ambiguity).
2. **Read-only by design.** We deliberately omit write operations even where the upstream APIs and stock servers offer them. This keeps AI workflows safe (no accidental edits), aligned with least-privilege and audit requirements, and deterministic — outputs are reviewable before anything is shared or acted on. Write workflows stay with dedicated, human-driven tools outside the MCP layer.
3. **Local bridge, OS-keychain secrets, cross-system reach.** The server runs locally and stores credentials in the OS keychain (not env-var tokens or a cloud-hosted OAuth broker). A unified `search`/`fetch` spans Jira and Confluence in one call, and browser tools can verify a live UI against a Figma design — orchestration the single-product stock servers can't do.

### Atlassian: out-of-the-box MCP vs. ours

| | Official Atlassian MCP | This toolchain |
|---|---|---|
| Surface area | One tool per operation (~25+ Jira/Confluence tools all in context) | Two intent tools — `jira` and `confluence` — plus unified `search`/`fetch` |
| Write access | Creates/edits/transitions issues, creates/updates pages and comments | Read-only by design — no accidental edits from AI |
| Routing | Model must pick the exact tool and field shape | Free-text intent → semantic routing + extractors pick the operation |
| Hosting / auth | Cloud-hosted, OAuth broker | Local bridge, OS-keychain credentials |
| Cross-system | Atlassian only | `search`/`fetch` join Jira + Confluence; composes with GitHub, M365, browser |

**Why ours is better and more flexible:** investigation and reporting are the common AI tasks against Atlassian, and those are read-only. We give the same data precision (issue details, metadata, comments, sprint/epic structure, full Confluence content with automatic chunking for large pages) without exposing destructive write paths, and we collapse the tool sprawl into intents the model can hit reliably. If you genuinely need to author content, use the Atlassian APIs or the official MCP for that step — keep AI-driven discovery here.

### Datadog: out-of-the-box MCP vs. ours

| | Official Datadog MCP | This toolchain |
|---|---|---|
| Surface area | Separate tools per data type (metrics, logs, monitors, dashboards, incidents, …) | One `datadog` intent tool routing to logs/metrics/monitors/dashboards/scopes |
| Coverage of new endpoints | Limited to the operations the server exposes today | Generic read proxy: `query_datadog_api_get` and `search_datadog_api_post` reach *any* allowlisted read endpoint |
| Safety | Capabilities depend on the granted API/app keys | Read-only scopes enforced; `get_datadog_supported_read_scopes` makes the boundary explicit |
| Auth | Vendor-defined | API + app key in the OS keychain, region/site configurable |

**Why ours is better and more flexible:** incident triage is the real workload — "which monitors are alerting, show me the error logs, plot this metric." Our intent tool covers that directly, and the generic read proxy means you are never blocked waiting for us to add a dedicated tool for a Datadog endpoint: if it's a read path under `/api/`, you can query it now. The read-only scope guarantee keeps it safe to point an AI agent at production observability.

### Figma: out-of-the-box MCP vs. ours

| | Official Figma (Dev Mode) MCP | This toolchain |
|---|---|---|
| Runtime requirement | Needs the Figma desktop app running locally with a node selected | Talks to the Figma REST API — no desktop app, works headless/CI |
| Focus | Design-to-code for the current selection; can create/edit designs | Read-only retrieval of files, nodes, comments, versions, components, styles, dev resources, images, **design specs**, and **page screenshots** |
| Surface area | Multiple discrete tools | One `figma` intent tool; paste a Figma URL and describe what you need |
| Unique capability | — | `browser_compare_figma_styles` checks a live localhost UI against the Figma design; `browser_verify_user_intent` validates implemented vs. intended |

**Why ours is better and more flexible:** the stock Figma MCP is tied to the desktop app and oriented toward generating designs, which makes it awkward for automated review and CI. Ours pulls design context over the REST API from anywhere, and — uniquely — bridges into the browser toolset so an agent can compare what shipped in the running app against the source-of-truth design. That design-vs-implementation check is the high-value workflow for engineers, and no single-product server offers it.

## Why the GitHub tools are better for day-to-day usage

GitHub is the system of record for implementation details, code history, and reviews. The GitHub toolset is modeled around common engineering tasks:

- Find usage examples or patterns with `search_github_code`
- Open exact files and line ranges with `get_github_file`
- Check current activity with `get_github_pull_requests`, `get_github_issues`, and `get_github_commits`
- Trace change context with `get_github_commit` and PR detail views

This makes GitHub tools the fastest path from question to verified source, which is essential for day-to-day development, debugging, and review work.

## Requirements

- Node.js 18+
- npm

## Install

```bash
npm install
```

## Build

```bash
npm run build
```

## Run

```bash
npm run start
```

## Development

```bash
npm run dev
```

## Tests

```bash
npm test
```

## Browser Automation Guidance

For browser MCP reliability and roadmap details, see:

- `docs/browser-agent-playbook.md` for deterministic agent operation patterns.
- `docs/browser-tools-rfc.md` for proposed tool additions and response-contract improvements.

## MCP smoke test

To verify a running HTTP MCP endpoint without hand-crafting SSE/session headers:

```bash
npm run smoke:mcp
```

Optional arguments:

```bash
npm run smoke:mcp -- --url http://127.0.0.1:6130/mcp
```

## Packaging

```bash
npm run package
```

## Install MCPipe Toolchain
Use this guide to install the tool from the GitHub Actions artifact, then configure GitHub authentication.

1. Download the correct artifact (by OS)
Open this workflow run:

https://github.com/mcpipe/mcpipe-toolchain/actions/runs/22774217374

From Artifacts, download the package matching your OS:

Windows: dist-app-windows-latest

macOS: dist-app-macos-latest (name may vary slightly)

Linux: dist-app-linux-latest (name may vary slightly)

2. Extract the artifact
Extract all files from the downloaded artifact to a local folder.

3. Run the application
Windows:
macOS: Open the extracted .app, .dmg, or .pkg and complete installation.
Linux: Run the extracted binary/AppImage (make executable first if needed).
One should see Icon of MCP Tool chain and start the server

<img width="239" height="228" alt="image" src="https://github.com/user-attachments/assets/2782db09-d45b-47e2-9dcf-790d1a3b51fd" />

<img width="1260" height="792" alt="image" src="https://github.com/user-attachments/assets/239fd767-f9ca-4369-928c-6a3268649b66" />

5. Create a GitHub Fine-Grained Personal Access Token
Go to GitHub: Profile -> Settings -> Developer settings
Open Personal access tokens -> Fine-grained tokens
Click Generate new token
Set required repository access/permissions for MCP tool usage
Generate the token and copy it

7. Configure token in MCP Toolchain
Open the MCP Toolchain application
Paste the copied token into the GitHub token field in the UI
Save/apply settings