agent-intel-mcp

agent-intel-mcp is an OpenAI-powered developer intelligence MCP server. It scans high-signal GitHub repositories, extracts reusable agent-engineering patterns, clusters them, compares them against a local codebase, and proposes safe AGENTS.md improvements.

This version moves beyond a thin MVP:

• Deep local codebase scanning with conventions and gap detection
• OpenAI Responses API for suggestion synthesis
• OpenAI embeddings for pattern clustering with heuristic fallback
• MCP stdio server with tools, resources, and prompts
• GitHub repository scanning with relevance scoring
• AGENTS.md patch preview generation
• SQLite-backed local memory for scans, clusters, suggestions, and dashboard history
• CI, release, and deploy scaffolding for portfolio-ready delivery

What This Project Proves

• OpenAI integration beyond chat wrappers
• MCP server design for agent clients
• GitHub mining and local repo analysis in one workflow
• safe patch generation instead of blind repository mutation
• TypeScript developer tooling with tests, CI, and release scaffolding

Demo Preview

Architecture

+---------------------------------------------------------------+
| agent-intel-mcp                                               |
|                                                               |
|  MCP Server (stdio)                                           |
|  |- Tools: scan, extract, cluster, analyze, suggest, patch    |
|  |- Resources: scans, patterns, clusters, local profile, patch|
|  `- Prompts: summary, AGENTS rewrite                          |
|                                                               |
|  Core Engine                                                  |
|  |- GithubScanner          -> Octokit search + README fetch   |
|  |- PatternExtractor       -> heuristic pattern mining        |
|  |- PatternClusterer       -> embeddings / cosine clustering  |
|  |- LocalRepoProfiler      -> codebase conventions + gaps     |
|  |- OpenAiSuggestionEngine -> Responses API / heuristic mode  |
|  |- PatchBuilder           -> non-destructive AGENTS diff     |
|  `- SqliteStore            -> scans, patterns, clusters       |
+---------------------------------------------------------------+

More detail: docs/ARCHITECTURE.md Case study: docs/CASE_STUDY.md

Tools

• scan_github_repos
• extract_patterns
• cluster_patterns
• analyze_local_repo
• generate_suggestions
• generate_agents_patch

Quick Start

npm install
cp .env.example .env
npm run build
npm test
npm run demo:seed
npm run demo

Open http://localhost:4321.

Run With .env

Create a local .env in the project root:

OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
LOCAL_REPO_PATH=C:\Users\syfsy\projekty\agent-intel-mcp

Then run:

npm install
npm run build
npm run demo

Use .env when you want real OpenAI-backed suggestions or a different local repository target.

Run Demo Against Another Repo

PowerShell example:

$env:LOCAL_REPO_PATH="C:\Users\syfsy\projekty\some-other-repo"
npm run demo

Or put that path into .env:

LOCAL_REPO_PATH=C:\Users\syfsy\projekty\some-other-repo

What changes in this mode:

• local stack analysis points at the other repo
• detected gaps and conventions come from the other repo
• generated AGENTS.md patch is tailored to the other repo

Connect As An MCP Server

Build first:

npm install
npm run build

Then add it to your MCP client config:

{
  "mcpServers": {
    "agent-intel": {
      "command": "node",
      "args": ["C:/Users/syfsy/projekty/agent-intel-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GITHUB_TOKEN": "ghp_...",
        "LOCAL_REPO_PATH": "C:/Users/syfsy/projekty/agent-intel-mcp"
      }
    }
  }
}

After restart, the MCP client will see these tools:

• scan_github_repos
• extract_patterns
• cluster_patterns
• analyze_local_repo
• generate_suggestions
• generate_agents_patch

Environment

Variable	Default	Description
OPENAI_API_KEY	unset	Enables model-backed suggestions and embeddings
OPENAI_MODEL	gpt-5-mini	OpenAI model used for suggestion generation
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	Model used for pattern clustering
GITHUB_TOKEN	unset	Raises GitHub API limits and private-org access
CLUSTER_SIMILARITY_THRESHOLD	0.82	Cosine threshold for embedding-based clusters
LOCAL_REPO_PATH	process.cwd()	Repository profiled for AGENTS.md suggestions
AGENT_INTEL_DATA_DIR	.agent-intel	SQLite and cached outputs

Demo UX

• Local dashboard served from http://localhost:4321
• Real pipeline trigger: fresh scan, clustering, local gap analysis, patch preview, and history charts
• Seeded portfolio state via npm run demo:seed
• Safe patch preview keeps suggested AGENTS.md changes reviewable before any adoption
• Frontend files: public/index.html, public/styles.css, public/app.js

Release Readiness

• CI: ci.yml
• Tagged release publishing: release.yml
• Package validation: npm run release:check

Deploy Preview

The repo ships with Docker and Render scaffolding:

• Dockerfile
• render.yaml

Recommended path:

1. Push the repo to GitHub.
2. Create a Render web service from the repo.
3. Add OPENAI_API_KEY and GITHUB_TOKEN if you want live model-backed scans.
4. Use /healthz as the health check.
5. Deploy and open the generated public URL as the portfolio preview.

Why OpenAI Here

This implementation uses the OpenAI Responses API for suggestion synthesis and the embeddings API for semantic clustering. Current official docs also describe tool-driven workflows and remote MCP support: Using tools and Developer quickstart.