agent-intel-mcp

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

!Agent Intel Console desktop

!Agent Intel Console walkthrough

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.