Implementation Intelligence MCP

An MCP server that finds the best existing implementation for each software problem, extracts only the necessary knowledge, and packages it for an AI coding agent to integrate.

Not "GitHub search for LLMs". The differentiated work is the deciding: which repositories are worth reusing, which parts of them matter, in what mode you may legally use them, and what has to change to make them fit your project.

FEATURE:      resumable background file downloader with pause and retry   [Kotlin/Android]

RECOMMENDED:  tonyofrancis/Fetch
SCORE:        75/100  (confidence 81%)
REUSE MODE:   DIRECT_REUSE — Apache-2.0, matching stack (100%)
OBLIGATIONS:  Preserve copyright and NOTICE file · State significant changes
KEY SYMBOLS:  canResumeDownload · canRetryDownload · canPauseDownload · FileServerDownloader
COMPLETENESS: 7/10 evidenced   (✗ sends Range header, ✗ bounded retry count)
INTEGRATION:  low — 17 runtime deps; self-contained
SOURCE:       github.com/tonyofrancis/Fetch  commit 11c2c45

Repositories considered 30 · deeply analysed 4
~29,782 raw → ~710 returned tokens · 97.6% reduction

What it does

Given "build an Android app with resumable background downloads", a coding agent normally either reinvents the feature or opens twenty GitHub tabs. This server answers, in one call:

Question	How
What already exists?	Multi-strategy GitHub search from a curated technology vocabulary
Which is best, and why?	12 measured signals → an explainable 0–100 score
May I actually use it?	Licence × stack × architecture × your distribution model → a reuse mode
Which exact parts do I need?	The minimal connected symbol set, not the repository
What does it depend on?	Manifests parsed across 11 ecosystems
What tests prove it?	Test discovery, including which edge cases they cover
How do I adapt it to my project?	Source→target adaptation steps, and what to preserve

Division of labour

System	Job
GitHub	Find candidates
jCodeMunch	Understand candidates
This server	Decide what matters

jCodeMunch is optional. Without it the server degrades to GitHub file retrieval and says so on every affected result.

Install

git clone <this repo> && cd implementation-intelligence-mcp
npm install
npm run build

Requires Node ≥ 20. Optional but recommended: uv for the code index (uvx jcodemunch-mcp).

Authentication

No configuration is required. Token resolution, in order:

GITHUB_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GH_TOKEN → `gh auth token` → unauthenticated

If you already use the GitHub CLI, it works immediately.

Mode	Core	Search	Code search
Authenticated	5 000/hr	30/min	10/min
Unauthenticated	60/hr	10/min	—

Verify with npx implementation-mcp config (secrets are redacted).

Connect it to an MCP client

Claude Code

claude mcp add implementation-intelligence -- node /absolute/path/to/dist/index.js

Claude Desktop · Cursor · Windsurf

Add to claude_desktop_config.json (or your client's equivalent):

{
  "mcpServers": {
    "implementation-intelligence": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

env is optional if gh auth token works. Absolute paths — the client's working directory is not yours.

Verify

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' | node dist/index.js

Logs go to stderr only — stdout is the protocol channel.

The 8 tools

Deliberately 8, not 14. Internal analyzers are not tools: exposing every one of them inflates tool-selection difficulty and leaks internals into the model's context.

Tool	Use it when
`discover_implementations`	Before writing any non-trivial feature — "what exists, which is best?"
`get_implementation`	You have chosen a repository and need the symbols, deps and adaptation steps
`analyze_repository`	Evaluating one specific repository (`include:['license']`, `['tests']`, …)
`compare_implementations`	You have a shortlist and must choose
`build_implementation_plan`	"Build me an app that…" — decomposes, then plans across repositories
`analyze_target_project`	First, when integrating into an existing codebase
`find_alternative`	You tried something and hit a wall
`verify_implementation`	After adapting, before calling it done

Every spec capability remains reachable: find_tests / find_dependencies / check_license are analyze_repository(include:[…]); decompose_application is build_implementation_plan(mode:"decompose").

`discover_implementations`

{
  "feature": "resumable background file downloader with pause and retry",
  "requirements": ["pause/resume", "background execution", "persistent queue", "retry"],
  "language": "Kotlin",
  "platform": "Android",
  "distribution": "proprietary"
}

requirements is the highest-leverage field: each entry becomes a checklist item candidates are scored against. distribution changes licence verdicts materially — GPL is incompatible with a proprietary product but usually fine in an internal tool.

`get_implementation`

{
  "repository": "tonyofrancis/Fetch",
  "feature": "resumable download",
  "target_project_path": "/Users/me/myapp",
  "include_source": false
}

target_project_path turns generic advice into "add this under app/src/main/kotlin/data, which already holds your data access".

`find_alternative`

{
  "feature": "resumable downloader",
  "current_candidate": "owner/repo",
  "reason": "requires Room but this project uses SQLDelight"
}

The reason is parsed into a structured constraint and applied to ranking — the alternative is chosen for solving the thing that went wrong, not for being next-best. It also lists which other candidates fail the same constraint, so you know they were considered.

Example workflows

A feature inside an existing project

1. analyze_target_project { path: "/Users/me/myapp" }
2. discover_implementations { feature: "…", requirements: [...], language: <from step 1> }
3. get_implementation { repository: <winner>, target_project_path: "/Users/me/myapp" }
4. …implement…
5. verify_implementation { repository: <same>, feature: "…", target_project_path: "…" }

A whole application

1. build_implementation_plan { requirement: "…", mode: "decompose" }   ← instant, free
2. build_implementation_plan { requirement: "…", mode: "full" }        ← discovers per feature
3. get_implementation for each step, in the order given

Step 2 reports cross-repository conflicts before you write a line — verified live on three independently-chosen Android repositories:

CROSS-REPOSITORY CONFLICTS:
• DUPLICATE LOCAL DATABASE: two selections both pull androidx.room…
• DUPLICATE DEPENDENCY INJECTION: hilt-android, hilt-work, hilt-navigation-compose…
• DUPLICATE LOGGING: slf4j-api, slf4j-simple…

LICENCES (overall risk: high):
  strictest, which governs the combined work: UNKNOWN

When it goes wrong

find_alternative { feature: "…", current_candidate: "…", reason: "licence is AGPL and we ship proprietary" }

Architecture

        APP REQUIREMENT
              ↓
     FEATURE DECOMPOSER          "what features does this contain?"
              ↓
     IMPLEMENTATION PLANNER      "which are worth reusing, and what KIND to look for?"
              ↓
     GitHub discovery            quota-budgeted, multi-strategy
              ↓
     CANDIDATE EVIDENCE          12 axes: value + confidence + source + observation
              ↓
     RANKING ENGINE              explainable, reproducible, configurable
              ↓
     jCodeMunch                  symbol-level understanding of finalists
              ↓
     MINIMAL IMPLEMENTATION SET  smallest CONNECTED set that explains the feature
              ↓
     IMPLEMENTATION BUNDLE       + reuse mode, provenance, licence, metrics
              ↓
        CODING AGENT → build/test → (failure) → find_alternative ↺

Each stage is a separate module behind an interface, so a GitLab or Bitbucket provider, or a different code index, can be substituted without touching orchestration, ranking or context building. The reasoning behind each component is documented in the source.

Three signals that beat stars

Completeness — scored against your checklist. A 400-star repo implementing 7/7 beats a 40 000-star one implementing 3/7.

Integration surface — measured, not adjectival: symbols × runtime deps × integration points × configuration × framework coupling.

Reuse mode — the most decision-relevant field in the bundle:

Mode	Meaning
`DIRECT_REUSE`	Permissive licence, compatible stack and architecture — vendor or depend on it
`ADAPT`	Same language, different architecture — port the logic, replace the boundaries
`REFERENCE_ONLY`	Different language, or copyleft, or unmaintained — learn from it, write your own
`DO_NOT_USE`	Licence incompatible with your distribution model — with the reason stated

Licence gates everything: a perfect stack match under AGPL is DO_NOT_USE, not DIRECT_REUSE. Reuse mode multiplies the score, and the adjustment is recorded explicitly rather than applied silently.

No internal LLM calls

The server performs zero inference of its own. A model call inside it would move the token bill rather than remove it, and add latency, cost, non-determinism and a second failure mode.

Decomposition and query expansion run off a curated, versioned technology vocabulary — 36 capability clusters, 8 stack idiom sets:

"background resumable downloads"
        ↓
WorkManager · HTTP Range request · persistent job queue · exponential backoff · foreground service

Those are terms you would not have known to search for. A model could generate them; a curated table generates them reproducibly, testably, and for free.

Where a requirement is genuinely ambiguous, the ambiguity is returned rather than guessed — the calling agent already has a model and far more context about your intent.

Token optimisation

Retrieval is layered. You get L1 by default and ask for more.

Layer	Content	Cost
L1 Metadata	Repo, evidence, reuse mode, licence, confidence, explanation	~300–800 tok
L2 Implementation map	Minimal symbol set, signatures only	~500–2 000 tok
L3 Source	Source of named symbols, on request	on demand
L4 Tests	Test symbols and files, separately	on demand

Every bundle declares what it withheld and the exact call that would fetch it:

AVAILABLE ON REQUEST (not included, to save context):
• Source for 5 core symbol(s) (~1250 tokens) — get_implementation({"include_source":true})

Measured reductions

Operation	Raw	Returned	Reduction
`discover_implementations` (30 repos)	~29 782	~710	97.6%
`get_implementation` (one repo, deep)	~8 751	~1 609	81.6%
`build_implementation_plan` (89 repos, 9 deep)	~29 595	~932	96.9%

estimatedRawTokens counts only material actually retrieved, so the figure cannot be inflated by imagining reads that never happened. A test asserts raw > returned on live data.

We optimise useful information / token, not minimum tokens. Three fields bypass the budget entirely — reuse mode + licence, provenance, degradations — because a bundle that omits "you may not copy this" to save tokens is not smaller, it is dangerous.

Caching

search:v1:<hash>                short TTL   results legitimately change
repo:v1:owner/name              TTL         stars and pushes move
analysis:v1:owner/name@<sha>    IMMUTABLE   same commit ⇒ same source ⇒ same analysis
fingerprint:v1:owner/name@<sha> IMMUTABLE   which capabilities that source evidences

Cold: ~9 s. Warm: ~2 s with zero GitHub search calls.

Feature fingerprints are the seed of a local knowledge base: once a repository has been analysed, a later query for "download queue implementations" can shortlist it without touching GitHub search. The store is relational and indexed on (capability, strength), so lookup is an index scan.

CLI

The CLI uses the same services as the MCP server — there is no separate business logic.

implementation-mcp search "resumable Android downloader" -l Kotlin -p Android --diagnostics
implementation-mcp decompose "a social app with auth, feeds and messaging" -l Kotlin
implementation-mcp analyze square/okhttp --include license tests
implementation-mcp extract tonyofrancis/Fetch --feature "resumable download" --target ~/myapp
implementation-mcp compare --feature "HTTP client" square/okhttp ktorio/ktor
implementation-mcp plan "an app that downloads media in the background" -l Kotlin -n 4
implementation-mcp project ~/myapp
implementation-mcp alternative --feature "downloader" --reason "requires Room but we use SQLDelight"
implementation-mcp verify --repository tonyofrancis/Fetch --feature "resumable download" ~/myapp
implementation-mcp config
implementation-mcp cache --clear

--json on any command emits structured output for scripting.

Configuration

Every value is optional; see .env.example for all of them with rationale.

Variable	Default	Notes
`GITHUB_TOKEN`	—	Falls back to `gh auth token`, then unauthenticated
`ENABLE_CODE_INDEX`	`true`	jCodeMunch for symbol-level analysis
`CACHE_PATH`	`~/.implementation-mcp/cache.sqlite`
`MAX_REPOSITORIES`	`40`	Lowering this materially hurts quality — see Limitations
`MAX_DEEP_ANALYSIS`	`5`	Each costs several API calls
`MAX_CONTEXT_TOKENS`	`6000`	A ceiling, not a target
`RANKING_WEIGHTS`	—	JSON override; merged over defaults and renormalised
`ENABLE_DIAGNOSTICS`	`false`	Attach the metrics block to every result

Ranking weights are configurable and renormalised, so total stays a true 0–100 across any weight set:

RANKING_WEIGHTS='{"licenseCompatibility":0.20,"popularity":0.01}'

Limitations

Stated plainly, because a tool that hides these is worse than one that does not exist.

Search breadth matters more than ranking. With MAX_REPOSITORIES=12 an HTTP-client query returned a poor match; at the default 40, aiohttp/urllib3/requests surfaced immediately. The ranker was fine; the pool was too small. Do not lower it to save time.
Code search is 10/min. It is a scarce, high-signal channel spent only on finalists.
Static analysis only. Nothing from a repository is ever executed (see SECURITY.md). Dynamically-computed dependencies are missed, and marked inferred rather than guessed.
Architecture inference is pattern-matching, not comprehension. It reports unrecognised / bespoke with low confidence rather than inventing a pattern.
Completeness matching is lexical. A capability implemented under wholly unexpected naming can be missed — reported as unknown, distinct from absent.
verify_implementation caps confidence at 80% and compiles nothing. It catches the boring omissions (missing dependency, missing tests, missing attribution) that cause most integration failures. It cannot establish correctness.
Quality is inferred from signals, never proven. Every score ships its explanation so you can disagree.
The knowledge base starts empty. Fingerprints accumulate as you use it.

Licence considerations

Every licence verdict this server emits is advisory and is not legal advice. That disclaimer is attached to every licence-bearing response, and it is not decoration.

Licence is read from the LICENSE file and the provider's SPDX detection — never from prose claims in a README, which are attacker-controlled.

Compatibility is evaluated against your distribution model, because that is what determines real risk:

Licence	Proprietary	Internal-only	Open source
GPL-3.0	✗ incompatible	? unclear (until you ship)	✓ compatible
AGPL-3.0	✗ incompatible	? unclear	? network use = distribution
MPL-2.0	✓ (file-level only)	✓	✓

Missing or ambiguous licensing produces a loud warning, never an assumption of reusability. The exact wording, from the spec: "Repository does not contain a clearly identifiable license. Do not assume the code is freely reusable."
Combining repositories is strictly worse than any single choice: the strictest licence governs the combined work. build_implementation_plan reports this explicitly.
Reusing code this server surfaces means taking on that code's obligations, not this project's. See LICENSE.md.

Development

npm run typecheck
npm run test              # unit + security + perf
npm run test:integration  # live GitHub + jCodeMunch (auto-skips without credentials)
npm run build

~400 tests. The live integration suites are worth their quota: they have caught bugs no stub could — a repository whose release history is git tags rather than GitHub Releases, a code index returning YAML config keys as "symbols", a hostile repository description echoing its payload through a marker the unit tests considered safe.

Contributions should follow the pattern already in the source: state the decision, state the trade-off, and record the bug that motivated it. Several comments exist specifically because a subtle failure was expensive to find, and deleting them would invite the same bug back.

Licence

Apache-2.0. See LICENSE.md.

Name		Name	Last commit message	Last commit date
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Implementation Intelligence MCP

Contents

What it does

Division of labour

Install

Authentication

Connect it to an MCP client

Claude Code

Claude Desktop · Cursor · Windsurf

Verify

The 8 tools

`discover_implementations`

`get_implementation`

`find_alternative`

Example workflows

A feature inside an existing project

A whole application

When it goes wrong

Architecture

Three signals that beat stars

No internal LLM calls

Token optimisation

Measured reductions

Caching

CLI

Configuration

Limitations

Licence considerations

Development

Licence

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Implementation Intelligence MCP

Contents

What it does

Division of labour

Install

Authentication

Connect it to an MCP client

Claude Code

Claude Desktop · Cursor · Windsurf

Verify

The 8 tools

discover_implementations

get_implementation

find_alternative

Example workflows

A feature inside an existing project

A whole application

When it goes wrong

Architecture

Three signals that beat stars

No internal LLM calls

Token optimisation

Measured reductions

Caching

CLI

Configuration

Limitations

Licence considerations

Development

Licence

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`discover_implementations`

`get_implementation`

`find_alternative`