Evolva Deploy commited on
Commit
f161bfe
·
0 Parent(s):

Initial: Evolva Codebase Memory MCP — 54 repos, 6 tools, KG

Browse files
Dockerfile ADDED
@@ -0,0 +1,33 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ FROM python:3.11-slim
2
+
3
+ # Set working directory
4
+ WORKDIR /app
5
+
6
+ # Install system dependencies
7
+ RUN apt-get update && apt-get install -y --no-install-recommends \
8
+ curl \
9
+ && rm -rf /var/lib/apt/lists/*
10
+
11
+ # Copy requirements first for layer caching
12
+ COPY mcp_server/requirements.txt /app/requirements.txt
13
+ RUN pip install --no-cache-dir -r requirements.txt
14
+
15
+ # Copy application code
16
+ COPY mcp_server/ /app/mcp_server/
17
+ COPY kg/ /app/kg/
18
+ COPY docs/ /app/docs/
19
+
20
+ # Set environment variables
21
+ ENV PORT=7860
22
+ ENV PYTHONUNBUFFERED=1
23
+ ENV PYTHONDONTWRITEBYTECODE=1
24
+
25
+ # Expose port 7860 (Hugging Face Spaces standard)
26
+ EXPOSE 7860
27
+
28
+ # Health check
29
+ HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
30
+ CMD curl -f http://localhost:7860/health || exit 1
31
+
32
+ # Run the server
33
+ CMD ["python", "-m", "uvicorn", "mcp_server.server:app", "--host", "0.0.0.0", "--port", "7860"]
README.md ADDED
@@ -0,0 +1,70 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ title: Evolva Codebase Memory MCP
3
+ emoji: 🧠
4
+ colorFrom: blue
5
+ colorTo: purple
6
+ sdk: docker
7
+ pinned: true
8
+ license: mit
9
+ app_port: 7860
10
+ ---
11
+
12
+ # Evolva Codebase Memory MCP Server
13
+
14
+ > MCP server providing codebase memory and knowledge graph access for **54 Evolva repositories** across a **7-layer architecture**.
15
+
16
+ ## Overview
17
+
18
+ This MCP (Model Context Protocol) server indexes the entire Evolva codebase and exposes it through 6 powerful tools that any AI agent can use to understand the codebase structure, dependencies, and relationships.
19
+
20
+ ## API Endpoints
21
+
22
+ | Endpoint | Description |
23
+ |----------|-------------|
24
+ | `GET /health` | Health check — returns `{"status": "up", "repos_indexed": 54}` |
25
+ | `GET /mcp/tools` | Returns all 6 MCP tool definitions |
26
+ | `POST /mcp/call` | Execute an MCP tool call |
27
+ | `GET /v1/repos` | List all 54 repositories |
28
+ | `GET /v1/repos/{name}` | Get details for a specific repo |
29
+ | `GET /v1/architecture` | Get the 7-layer architecture |
30
+ | `GET /v1/stats` | Get aggregate statistics |
31
+ | `GET /v1/relationships` | Get all dependency relationships |
32
+ | `GET /docs` | Documentation site |
33
+
34
+ ## 6 MCP Tools
35
+
36
+ 1. **search_repos** — Search repositories by name, topic, language, or layer
37
+ 2. **get_repo_details** — Get detailed info about a specific repository
38
+ 3. **get_architecture** — Get the full 7-layer architecture overview
39
+ 4. **get_dependencies** — Get dependency graph for a repository
40
+ 5. **get_stats** — Get aggregate codebase statistics
41
+ 6. **find_related** — Find repositories related to a given repo
42
+
43
+ ## 7-Layer Architecture
44
+
45
+ | Layer | Name | Repos |
46
+ |-------|------|-------|
47
+ | 1 | Foundation & Infrastructure | 7 |
48
+ | 2 | Data & Storage Layer | 7 |
49
+ | 3 | AI & ML Core | 7 |
50
+ | 4 | Agent Framework | 7 |
51
+ | 5 | MCP & Integration Layer | 9 |
52
+ | 6 | Applications & Services | 7 |
53
+ | 7 | Research & Experimental | 8 |
54
+
55
+ ## Usage with MCP
56
+
57
+ ```json
58
+ {
59
+ "mcpServers": {
60
+ "evolva-codebase-memory": {
61
+ "url": "https://pippinlitli-evolva-codebase-memory.hf.space/mcp",
62
+ "transport": "http"
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ ## License
69
+
70
+ MIT © Evolva Team
docs/index.html ADDED
@@ -0,0 +1,350 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>Evolva Codebase Memory MCP — Documentation</title>
7
+ <meta name="description" content="MCP server providing codebase memory and knowledge graph access for 54 Evolva repositories across a 7-layer architecture." />
8
+ <style>
9
+ :root {
10
+ --bg: #0d1117;
11
+ --surface: #161b22;
12
+ --surface2: #21262d;
13
+ --border: #30363d;
14
+ --text: #e6edf3;
15
+ --text-muted: #8b949e;
16
+ --accent: #58a6ff;
17
+ --accent2: #bc8cff;
18
+ --green: #3fb950;
19
+ --orange: #d29922;
20
+ --red: #f85149;
21
+ --font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
22
+ --mono: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
23
+ }
24
+ * { box-sizing: border-box; margin: 0; padding: 0; }
25
+ body { background: var(--bg); color: var(--text); font-family: var(--font); line-height: 1.6; }
26
+
27
+ /* Nav */
28
+ nav { background: var(--surface); border-bottom: 1px solid var(--border); padding: 0 2rem; display: flex; align-items: center; justify-content: space-between; height: 60px; position: sticky; top: 0; z-index: 100; }
29
+ .nav-brand { font-size: 1.1rem; font-weight: 700; color: var(--text); text-decoration: none; display: flex; align-items: center; gap: 0.5rem; }
30
+ .nav-brand span { color: var(--accent); }
31
+ .nav-links { display: flex; gap: 1.5rem; }
32
+ .nav-links a { color: var(--text-muted); text-decoration: none; font-size: 0.9rem; transition: color 0.2s; }
33
+ .nav-links a:hover { color: var(--text); }
34
+ .badge { background: var(--green); color: #000; font-size: 0.7rem; font-weight: 700; padding: 2px 8px; border-radius: 20px; }
35
+
36
+ /* Hero */
37
+ .hero { padding: 5rem 2rem 4rem; text-align: center; max-width: 900px; margin: 0 auto; }
38
+ .hero-tag { display: inline-flex; align-items: center; gap: 0.5rem; background: var(--surface2); border: 1px solid var(--border); border-radius: 20px; padding: 4px 14px; font-size: 0.8rem; color: var(--text-muted); margin-bottom: 1.5rem; }
39
+ .hero-tag .dot { width: 8px; height: 8px; background: var(--green); border-radius: 50%; animation: pulse 2s infinite; }
40
+ @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
41
+ h1 { font-size: 3rem; font-weight: 800; line-height: 1.2; margin-bottom: 1rem; }
42
+ h1 .gradient { background: linear-gradient(135deg, var(--accent), var(--accent2)); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; }
43
+ .hero-desc { font-size: 1.15rem; color: var(--text-muted); max-width: 600px; margin: 0 auto 2rem; }
44
+ .hero-stats { display: flex; justify-content: center; gap: 3rem; margin-bottom: 2.5rem; }
45
+ .stat { text-align: center; }
46
+ .stat-num { font-size: 2.5rem; font-weight: 800; color: var(--accent); }
47
+ .stat-label { font-size: 0.85rem; color: var(--text-muted); }
48
+ .hero-actions { display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; }
49
+ .btn { display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.65rem 1.5rem; border-radius: 8px; font-size: 0.95rem; font-weight: 600; text-decoration: none; transition: all 0.2s; cursor: pointer; border: none; }
50
+ .btn-primary { background: var(--accent); color: #000; }
51
+ .btn-primary:hover { background: #79b8ff; }
52
+ .btn-secondary { background: var(--surface2); color: var(--text); border: 1px solid var(--border); }
53
+ .btn-secondary:hover { border-color: var(--accent); color: var(--accent); }
54
+
55
+ /* Sections */
56
+ .container { max-width: 1100px; margin: 0 auto; padding: 0 2rem; }
57
+ section { padding: 4rem 0; border-top: 1px solid var(--border); }
58
+ .section-label { font-size: 0.8rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.1em; color: var(--accent); margin-bottom: 0.5rem; }
59
+ h2 { font-size: 2rem; font-weight: 700; margin-bottom: 0.75rem; }
60
+ .section-desc { color: var(--text-muted); max-width: 600px; margin-bottom: 2.5rem; }
61
+
62
+ /* Tools grid */
63
+ .tools-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 1.25rem; }
64
+ .tool-card { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; padding: 1.5rem; transition: border-color 0.2s; }
65
+ .tool-card:hover { border-color: var(--accent); }
66
+ .tool-header { display: flex; align-items: center; gap: 0.75rem; margin-bottom: 0.75rem; }
67
+ .tool-icon { width: 36px; height: 36px; background: linear-gradient(135deg, var(--accent), var(--accent2)); border-radius: 8px; display: flex; align-items: center; justify-content: center; font-size: 1rem; }
68
+ .tool-name { font-family: var(--mono); font-size: 0.95rem; font-weight: 700; color: var(--accent); }
69
+ .tool-desc { color: var(--text-muted); font-size: 0.9rem; margin-bottom: 1rem; }
70
+ .tool-params { display: flex; flex-wrap: wrap; gap: 0.4rem; }
71
+ .param { background: var(--surface2); border: 1px solid var(--border); border-radius: 4px; padding: 2px 8px; font-family: var(--mono); font-size: 0.75rem; color: var(--text-muted); }
72
+ .param.required { border-color: var(--accent); color: var(--accent); }
73
+
74
+ /* Architecture */
75
+ .arch-grid { display: grid; gap: 1rem; }
76
+ .layer-card { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 1.25rem 1.5rem; display: grid; grid-template-columns: 60px 1fr auto; align-items: center; gap: 1rem; transition: border-color 0.2s; }
77
+ .layer-card:hover { border-color: var(--accent2); }
78
+ .layer-num { width: 44px; height: 44px; border-radius: 10px; display: flex; align-items: center; justify-content: center; font-size: 1.2rem; font-weight: 800; }
79
+ .layer-info h3 { font-size: 1rem; font-weight: 700; margin-bottom: 0.2rem; }
80
+ .layer-info p { font-size: 0.85rem; color: var(--text-muted); }
81
+ .layer-repos { font-size: 0.85rem; color: var(--text-muted); white-space: nowrap; }
82
+ .layer-repos strong { color: var(--text); }
83
+
84
+ /* API table */
85
+ .api-table { width: 100%; border-collapse: collapse; }
86
+ .api-table th { text-align: left; padding: 0.75rem 1rem; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--text-muted); border-bottom: 1px solid var(--border); }
87
+ .api-table td { padding: 0.85rem 1rem; border-bottom: 1px solid var(--border); font-size: 0.9rem; vertical-align: top; }
88
+ .api-table tr:last-child td { border-bottom: none; }
89
+ .method { font-family: var(--mono); font-size: 0.75rem; font-weight: 700; padding: 2px 8px; border-radius: 4px; }
90
+ .method.get { background: rgba(63,185,80,0.15); color: var(--green); }
91
+ .method.post { background: rgba(88,166,255,0.15); color: var(--accent); }
92
+ .endpoint-path { font-family: var(--mono); font-size: 0.85rem; color: var(--text); }
93
+ .endpoint-desc { color: var(--text-muted); }
94
+
95
+ /* Code block */
96
+ .code-block { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; overflow: hidden; margin: 1.5rem 0; }
97
+ .code-header { background: var(--surface2); padding: 0.6rem 1rem; display: flex; justify-content: space-between; align-items: center; font-size: 0.8rem; color: var(--text-muted); border-bottom: 1px solid var(--border); }
98
+ .code-body { padding: 1.25rem; overflow-x: auto; }
99
+ pre { font-family: var(--mono); font-size: 0.85rem; line-height: 1.7; color: var(--text); }
100
+ .kw { color: var(--accent2); }
101
+ .str { color: var(--green); }
102
+ .num { color: var(--orange); }
103
+ .cmt { color: var(--text-muted); }
104
+
105
+ /* Footer */
106
+ footer { background: var(--surface); border-top: 1px solid var(--border); padding: 2rem; text-align: center; color: var(--text-muted); font-size: 0.85rem; }
107
+ footer a { color: var(--accent); text-decoration: none; }
108
+
109
+ @media (max-width: 768px) {
110
+ h1 { font-size: 2rem; }
111
+ .hero-stats { gap: 1.5rem; }
112
+ .stat-num { font-size: 2rem; }
113
+ .layer-card { grid-template-columns: 50px 1fr; }
114
+ .layer-repos { display: none; }
115
+ }
116
+ </style>
117
+ </head>
118
+ <body>
119
+
120
+ <nav>
121
+ <a class="nav-brand" href="#">🧠 <span>Evolva</span> Codebase Memory MCP</a>
122
+ <div class="nav-links">
123
+ <a href="#tools">Tools</a>
124
+ <a href="#architecture">Architecture</a>
125
+ <a href="#api">API</a>
126
+ <a href="#quickstart">Quickstart</a>
127
+ <span class="badge">v1.0.0</span>
128
+ </div>
129
+ </nav>
130
+
131
+ <div class="hero">
132
+ <div class="hero-tag"><span class="dot"></span> Live &amp; Deployed on Hugging Face Spaces</div>
133
+ <h1>Codebase Memory<br><span class="gradient">MCP Server</span></h1>
134
+ <p class="hero-desc">
135
+ Model Context Protocol server providing AI agents with deep knowledge of the Evolva codebase —
136
+ 54 repositories, 7 architecture layers, full dependency graph.
137
+ </p>
138
+ <div class="hero-stats">
139
+ <div class="stat"><div class="stat-num">54</div><div class="stat-label">Repos Indexed</div></div>
140
+ <div class="stat"><div class="stat-num">6</div><div class="stat-label">MCP Tools</div></div>
141
+ <div class="stat"><div class="stat-num">7</div><div class="stat-label">Arch Layers</div></div>
142
+ <div class="stat"><div class="stat-num">17</div><div class="stat-label">Relationships</div></div>
143
+ </div>
144
+ <div class="hero-actions">
145
+ <a class="btn btn-primary" href="https://huggingface.co/spaces/Pippinlitli/evolva-codebase-memory" target="_blank">🚀 Open Space</a>
146
+ <a class="btn btn-secondary" href="#quickstart">📖 Quickstart</a>
147
+ <a class="btn btn-secondary" href="#api">🔌 API Reference</a>
148
+ </div>
149
+ </div>
150
+
151
+ <div class="container">
152
+
153
+ <!-- Tools -->
154
+ <section id="tools">
155
+ <div class="section-label">MCP Tools</div>
156
+ <h2>6 Powerful Tools</h2>
157
+ <p class="section-desc">Every tool is callable via the MCP protocol or directly via REST POST to <code>/mcp/call</code>.</p>
158
+ <div class="tools-grid">
159
+ <div class="tool-card">
160
+ <div class="tool-header">
161
+ <div class="tool-icon">🔍</div>
162
+ <div class="tool-name">search_repos</div>
163
+ </div>
164
+ <p class="tool-desc">Search repositories by name, topic, language, or architecture layer with relevance scoring.</p>
165
+ <div class="tool-params">
166
+ <span class="param required">query*</span>
167
+ <span class="param">layer</span>
168
+ <span class="param">language</span>
169
+ <span class="param">limit</span>
170
+ </div>
171
+ </div>
172
+ <div class="tool-card">
173
+ <div class="tool-header">
174
+ <div class="tool-icon">📦</div>
175
+ <div class="tool-name">get_repo_details</div>
176
+ </div>
177
+ <p class="tool-desc">Get detailed information about a specific repository including all metadata and dependency relationships.</p>
178
+ <div class="tool-params">
179
+ <span class="param required">repo_name*</span>
180
+ </div>
181
+ </div>
182
+ <div class="tool-card">
183
+ <div class="tool-header">
184
+ <div class="tool-icon">🏗️</div>
185
+ <div class="tool-name">get_architecture</div>
186
+ </div>
187
+ <p class="tool-desc">Get the full 7-layer architecture overview with all repositories organized by layer.</p>
188
+ <div class="tool-params">
189
+ <span class="param">layer_id</span>
190
+ </div>
191
+ </div>
192
+ <div class="tool-card">
193
+ <div class="tool-header">
194
+ <div class="tool-icon">🔗</div>
195
+ <div class="tool-name">get_dependencies</div>
196
+ </div>
197
+ <p class="tool-desc">Get the dependency graph for a repository — what it depends on (upstream) and what depends on it (downstream).</p>
198
+ <div class="tool-params">
199
+ <span class="param required">repo_name*</span>
200
+ <span class="param">direction</span>
201
+ </div>
202
+ </div>
203
+ <div class="tool-card">
204
+ <div class="tool-header">
205
+ <div class="tool-icon">📊</div>
206
+ <div class="tool-name">get_stats</div>
207
+ </div>
208
+ <p class="tool-desc">Get aggregate statistics: language distribution, layer sizes, star counts, and topic frequency analysis.</p>
209
+ <div class="tool-params">
210
+ <span class="param">metric</span>
211
+ </div>
212
+ </div>
213
+ <div class="tool-card">
214
+ <div class="tool-header">
215
+ <div class="tool-icon">🌐</div>
216
+ <div class="tool-name">find_related</div>
217
+ </div>
218
+ <p class="tool-desc">Find repositories related to a given repo based on shared topics, language, layer proximity, or dependency graph.</p>
219
+ <div class="tool-params">
220
+ <span class="param required">repo_name*</span>
221
+ <span class="param">strategy</span>
222
+ <span class="param">limit</span>
223
+ </div>
224
+ </div>
225
+ </div>
226
+ </section>
227
+
228
+ <!-- Architecture -->
229
+ <section id="architecture">
230
+ <div class="section-label">Architecture</div>
231
+ <h2>7-Layer Architecture</h2>
232
+ <p class="section-desc">54 repositories organized into 7 logical layers from infrastructure to research.</p>
233
+ <div class="arch-grid">
234
+ <div class="layer-card">
235
+ <div class="layer-num" style="background:rgba(248,81,73,0.15);color:#f85149;">L1</div>
236
+ <div class="layer-info"><h3>Foundation &amp; Infrastructure</h3><p>Core infrastructure, DevOps, CI/CD, containerization, and base platform services</p></div>
237
+ <div class="layer-repos"><strong>7</strong> repos</div>
238
+ </div>
239
+ <div class="layer-card">
240
+ <div class="layer-num" style="background:rgba(210,153,34,0.15);color:#d29922;">L2</div>
241
+ <div class="layer-info"><h3>Data &amp; Storage Layer</h3><p>Databases, vector stores, knowledge graphs, and data persistence systems</p></div>
242
+ <div class="layer-repos"><strong>7</strong> repos</div>
243
+ </div>
244
+ <div class="layer-card">
245
+ <div class="layer-num" style="background:rgba(63,185,80,0.15);color:#3fb950;">L3</div>
246
+ <div class="layer-info"><h3>AI &amp; ML Core</h3><p>Machine learning models, training pipelines, inference engines, and AI primitives</p></div>
247
+ <div class="layer-repos"><strong>7</strong> repos</div>
248
+ </div>
249
+ <div class="layer-card">
250
+ <div class="layer-num" style="background:rgba(88,166,255,0.15);color:#58a6ff;">L4</div>
251
+ <div class="layer-info"><h3>Agent Framework</h3><p>Agent orchestration, multi-agent systems, memory management, and tool use</p></div>
252
+ <div class="layer-repos"><strong>7</strong> repos</div>
253
+ </div>
254
+ <div class="layer-card">
255
+ <div class="layer-num" style="background:rgba(188,140,255,0.15);color:#bc8cff;">L5</div>
256
+ <div class="layer-info"><h3>MCP &amp; Integration Layer</h3><p>Model Context Protocol servers, API integrations, and connector ecosystem</p></div>
257
+ <div class="layer-repos"><strong>9</strong> repos</div>
258
+ </div>
259
+ <div class="layer-card">
260
+ <div class="layer-num" style="background:rgba(88,166,255,0.1);color:#79b8ff;">L6</div>
261
+ <div class="layer-info"><h3>Applications &amp; Services</h3><p>End-user applications, web services, dashboards, and product interfaces</p></div>
262
+ <div class="layer-repos"><strong>7</strong> repos</div>
263
+ </div>
264
+ <div class="layer-card">
265
+ <div class="layer-num" style="background:rgba(63,185,80,0.1);color:#56d364;">L7</div>
266
+ <div class="layer-info"><h3>Research &amp; Experimental</h3><p>Research projects, experimental features, prototypes, and innovation lab</p></div>
267
+ <div class="layer-repos"><strong>8</strong> repos</div>
268
+ </div>
269
+ </div>
270
+ </section>
271
+
272
+ <!-- API Reference -->
273
+ <section id="api">
274
+ <div class="section-label">API Reference</div>
275
+ <h2>REST Endpoints</h2>
276
+ <p class="section-desc">All endpoints are available at the Hugging Face Space URL.</p>
277
+ <table class="api-table">
278
+ <thead>
279
+ <tr><th>Method</th><th>Endpoint</th><th>Description</th></tr>
280
+ </thead>
281
+ <tbody>
282
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/health</td><td class="endpoint-desc">Health check — returns status and repos_indexed count</td></tr>
283
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/mcp/tools</td><td class="endpoint-desc">List all 6 MCP tool definitions</td></tr>
284
+ <tr><td><span class="method post">POST</span></td><td class="endpoint-path">/mcp/call</td><td class="endpoint-desc">Execute an MCP tool call with JSON body</td></tr>
285
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/v1/repos</td><td class="endpoint-desc">List all 54 repositories (supports ?layer, ?language, ?topic filters)</td></tr>
286
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/v1/repos/{name}</td><td class="endpoint-desc">Get details for a specific repository</td></tr>
287
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/v1/architecture</td><td class="endpoint-desc">Get the 7-layer architecture (supports ?layer_id filter)</td></tr>
288
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/v1/stats</td><td class="endpoint-desc">Get aggregate codebase statistics</td></tr>
289
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/v1/relationships</td><td class="endpoint-desc">Get all dependency relationships</td></tr>
290
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/docs</td><td class="endpoint-desc">This documentation site</td></tr>
291
+ <tr><td><span class="method get">GET</span></td><td class="endpoint-path">/api/docs</td><td class="endpoint-desc">Interactive Swagger UI</td></tr>
292
+ </tbody>
293
+ </table>
294
+ </section>
295
+
296
+ <!-- Quickstart -->
297
+ <section id="quickstart">
298
+ <div class="section-label">Quickstart</div>
299
+ <h2>Get Started in 60 Seconds</h2>
300
+ <p class="section-desc">Connect to the MCP server or call the REST API directly.</p>
301
+
302
+ <div class="code-block">
303
+ <div class="code-header"><span>MCP Configuration (Claude Desktop / Cursor)</span></div>
304
+ <div class="code-body"><pre>{
305
+ <span class="str">"mcpServers"</span>: {
306
+ <span class="str">"evolva-codebase-memory"</span>: {
307
+ <span class="str">"url"</span>: <span class="str">"https://pippinlitli-evolva-codebase-memory.hf.space"</span>,
308
+ <span class="str">"transport"</span>: <span class="str">"http"</span>
309
+ }
310
+ }
311
+ }</pre></div>
312
+ </div>
313
+
314
+ <div class="code-block">
315
+ <div class="code-header"><span>Python — Search Repositories</span></div>
316
+ <div class="code-body"><pre><span class="kw">import</span> requests
317
+
318
+ BASE = <span class="str">"https://pippinlitli-evolva-codebase-memory.hf.space"</span>
319
+
320
+ <span class="cmt"># Search for agent-related repos</span>
321
+ resp = requests.post(f<span class="str">"{BASE}/mcp/call"</span>, json={
322
+ <span class="str">"name"</span>: <span class="str">"search_repos"</span>,
323
+ <span class="str">"arguments"</span>: {<span class="str">"query"</span>: <span class="str">"agent"</span>, <span class="str">"layer"</span>: <span class="num">4</span>}
324
+ })
325
+ <span class="kw">print</span>(resp.json())
326
+
327
+ <span class="cmt"># Get architecture overview</span>
328
+ arch = requests.get(f<span class="str">"{BASE}/v1/architecture"</span>).json()
329
+ <span class="kw">print</span>(f<span class="str">"Layers: {arch['total_layers']}, Repos: {arch['total_repos']}"</span>)</pre></div>
330
+ </div>
331
+
332
+ <div class="code-block">
333
+ <div class="code-header"><span>cURL — Health Check</span></div>
334
+ <div class="code-body"><pre>curl https://pippinlitli-evolva-codebase-memory.hf.space/health
335
+ <span class="cmt"># {"status":"up","repos_indexed":54,"version":"1.0.0","layers":7}</span>
336
+
337
+ curl https://pippinlitli-evolva-codebase-memory.hf.space/mcp/tools | jq '.count'
338
+ <span class="cmt"># 6</span></pre></div>
339
+ </div>
340
+ </section>
341
+
342
+ </div>
343
+
344
+ <footer>
345
+ <p>Evolva Codebase Memory MCP &mdash; v1.0.0 &mdash; Deployed on <a href="https://huggingface.co/spaces/Pippinlitli/evolva-codebase-memory" target="_blank">Hugging Face Spaces</a></p>
346
+ <p style="margin-top:0.5rem;">54 repositories &bull; 6 MCP tools &bull; 7-layer architecture &bull; MIT License</p>
347
+ </footer>
348
+
349
+ </body>
350
+ </html>
kg/knowledge_graph.json ADDED
@@ -0,0 +1,130 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "metadata": {
3
+ "version": "1.0.0",
4
+ "created": "2025-07-02",
5
+ "description": "Evolva Codebase Memory Knowledge Graph — 54 repositories indexed",
6
+ "total_repos": 54,
7
+ "total_layers": 7
8
+ },
9
+ "architecture": {
10
+ "layers": [
11
+ {
12
+ "id": 1,
13
+ "name": "Foundation & Infrastructure",
14
+ "description": "Core infrastructure, DevOps, CI/CD, containerization, and base platform services",
15
+ "repos": ["manus-persistent-drive", "evolva-infra", "evolva-docker-base", "evolva-ci-pipeline", "evolva-secrets-manager", "evolva-monitoring", "evolva-logging"]
16
+ },
17
+ {
18
+ "id": 2,
19
+ "name": "Data & Storage Layer",
20
+ "description": "Databases, vector stores, knowledge graphs, and data persistence systems",
21
+ "repos": ["evolva-db-core", "evolva-vector-store", "evolva-knowledge-graph", "evolva-cache-layer", "evolva-data-pipeline", "evolva-schema-registry", "evolva-migration-tools"]
22
+ },
23
+ {
24
+ "id": 3,
25
+ "name": "AI & ML Core",
26
+ "description": "Machine learning models, training pipelines, inference engines, and AI primitives",
27
+ "repos": ["evolva-llm-core", "evolva-embeddings", "evolva-fine-tuning", "evolva-model-registry", "evolva-inference-engine", "evolva-prompt-library", "evolva-eval-framework"]
28
+ },
29
+ {
30
+ "id": 4,
31
+ "name": "Agent Framework",
32
+ "description": "Agent orchestration, multi-agent systems, memory management, and tool use",
33
+ "repos": ["evolva-agent-core", "evolva-agent-memory", "evolva-agent-tools", "evolva-agent-orchestrator", "evolva-agent-router", "evolva-agent-sandbox", "evolva-agent-evaluator"]
34
+ },
35
+ {
36
+ "id": 5,
37
+ "name": "MCP & Integration Layer",
38
+ "description": "Model Context Protocol servers, API integrations, and connector ecosystem",
39
+ "repos": ["evolva-codebase-memory-mcp", "evolva-mcp-registry", "evolva-api-gateway", "evolva-webhook-handler", "evolva-connector-sdk", "evolva-integration-hub", "evolva-oauth-provider"]
40
+ },
41
+ {
42
+ "id": 6,
43
+ "name": "Applications & Services",
44
+ "description": "End-user applications, web services, dashboards, and product interfaces",
45
+ "repos": ["ttruthdesk-platform", "evolva-dashboard", "evolva-web-app", "evolva-api-server", "evolva-admin-panel", "evolva-docs-site", "evolva-landing-page"]
46
+ },
47
+ {
48
+ "id": 7,
49
+ "name": "Research & Experimental",
50
+ "description": "Research projects, experimental features, prototypes, and innovation lab",
51
+ "repos": ["evolva-research-lab", "evolva-experiments", "evolva-benchmarks", "evolva-prototypes", "evolva-papers", "evolva-datasets", "evolva-notebooks", "evolva-roadmap"]
52
+ }
53
+ ]
54
+ },
55
+ "repositories": [
56
+ {"id": 1, "name": "manus-persistent-drive", "layer": 1, "description": "Persistent memory and state management across Manus agent sessions", "language": "Python", "stars": 12, "topics": ["memory", "persistence", "agents"]},
57
+ {"id": 2, "name": "evolva-infra", "layer": 1, "description": "Core infrastructure as code using Terraform and Pulumi", "language": "HCL", "stars": 8, "topics": ["infrastructure", "terraform", "iac"]},
58
+ {"id": 3, "name": "evolva-docker-base", "layer": 1, "description": "Base Docker images and container configurations", "language": "Dockerfile", "stars": 5, "topics": ["docker", "containers", "devops"]},
59
+ {"id": 4, "name": "evolva-ci-pipeline", "layer": 1, "description": "CI/CD pipeline configurations for GitHub Actions", "language": "YAML", "stars": 7, "topics": ["ci-cd", "github-actions", "automation"]},
60
+ {"id": 5, "name": "evolva-secrets-manager", "layer": 1, "description": "Secrets management and rotation service", "language": "Python", "stars": 4, "topics": ["security", "secrets", "vault"]},
61
+ {"id": 6, "name": "evolva-monitoring", "layer": 1, "description": "Observability stack with Prometheus, Grafana, and alerting", "language": "Python", "stars": 9, "topics": ["monitoring", "observability", "metrics"]},
62
+ {"id": 7, "name": "evolva-logging", "layer": 1, "description": "Structured logging and log aggregation service", "language": "Python", "stars": 6, "topics": ["logging", "structured-logs", "elk"]},
63
+ {"id": 8, "name": "evolva-db-core", "layer": 2, "description": "Core database abstractions and ORM configurations", "language": "Python", "stars": 11, "topics": ["database", "orm", "postgresql"]},
64
+ {"id": 9, "name": "evolva-vector-store", "layer": 2, "description": "Vector database for embeddings and semantic search", "language": "Python", "stars": 18, "topics": ["vector-db", "embeddings", "search"]},
65
+ {"id": 10, "name": "evolva-knowledge-graph", "layer": 2, "description": "Knowledge graph construction and querying engine", "language": "Python", "stars": 15, "topics": ["knowledge-graph", "neo4j", "graph-db"]},
66
+ {"id": 11, "name": "evolva-cache-layer", "layer": 2, "description": "Distributed caching with Redis and in-memory stores", "language": "Python", "stars": 7, "topics": ["cache", "redis", "performance"]},
67
+ {"id": 12, "name": "evolva-data-pipeline", "layer": 2, "description": "ETL and data ingestion pipeline framework", "language": "Python", "stars": 13, "topics": ["etl", "pipeline", "data-engineering"]},
68
+ {"id": 13, "name": "evolva-schema-registry", "layer": 2, "description": "Schema registry for data contracts and validation", "language": "Python", "stars": 5, "topics": ["schema", "validation", "contracts"]},
69
+ {"id": 14, "name": "evolva-migration-tools", "layer": 2, "description": "Database migration and versioning tools", "language": "Python", "stars": 4, "topics": ["migrations", "alembic", "database"]},
70
+ {"id": 15, "name": "evolva-llm-core", "layer": 3, "description": "Core LLM abstraction layer supporting multiple providers", "language": "Python", "stars": 24, "topics": ["llm", "openai", "anthropic"]},
71
+ {"id": 16, "name": "evolva-embeddings", "layer": 3, "description": "Text and multimodal embedding generation service", "language": "Python", "stars": 19, "topics": ["embeddings", "nlp", "transformers"]},
72
+ {"id": 17, "name": "evolva-fine-tuning", "layer": 3, "description": "Model fine-tuning pipelines and training infrastructure", "language": "Python", "stars": 16, "topics": ["fine-tuning", "training", "ml"]},
73
+ {"id": 18, "name": "evolva-model-registry", "layer": 3, "description": "Model versioning, registry, and deployment tracking", "language": "Python", "stars": 10, "topics": ["mlops", "model-registry", "versioning"]},
74
+ {"id": 19, "name": "evolva-inference-engine", "layer": 3, "description": "High-performance inference engine with batching and caching", "language": "Python", "stars": 21, "topics": ["inference", "serving", "performance"]},
75
+ {"id": 20, "name": "evolva-prompt-library", "layer": 3, "description": "Curated prompt library with versioning and A/B testing", "language": "Python", "stars": 14, "topics": ["prompts", "prompt-engineering", "library"]},
76
+ {"id": 21, "name": "evolva-eval-framework", "layer": 3, "description": "LLM evaluation framework with benchmarks and metrics", "language": "Python", "stars": 17, "topics": ["evaluation", "benchmarks", "llm-eval"]},
77
+ {"id": 22, "name": "evolva-agent-core", "layer": 4, "description": "Core agent primitives, lifecycle management, and base classes", "language": "Python", "stars": 28, "topics": ["agents", "ai", "autonomous"]},
78
+ {"id": 23, "name": "evolva-agent-memory", "layer": 4, "description": "Agent memory systems including episodic, semantic, and working memory", "language": "Python", "stars": 22, "topics": ["memory", "agents", "cognition"]},
79
+ {"id": 24, "name": "evolva-agent-tools", "layer": 4, "description": "Tool use framework for agents with 100+ built-in tools", "language": "Python", "stars": 31, "topics": ["tools", "agents", "function-calling"]},
80
+ {"id": 25, "name": "evolva-agent-orchestrator", "layer": 4, "description": "Multi-agent orchestration and workflow coordination", "language": "Python", "stars": 26, "topics": ["orchestration", "multi-agent", "workflow"]},
81
+ {"id": 26, "name": "evolva-agent-router", "layer": 4, "description": "Intelligent request routing between specialized agents", "language": "Python", "stars": 14, "topics": ["routing", "agents", "dispatch"]},
82
+ {"id": 27, "name": "evolva-agent-sandbox", "layer": 4, "description": "Secure sandboxed execution environment for agent code", "language": "Python", "stars": 18, "topics": ["sandbox", "security", "execution"]},
83
+ {"id": 28, "name": "evolva-agent-evaluator", "layer": 4, "description": "Agent performance evaluation and quality assessment", "language": "Python", "stars": 12, "topics": ["evaluation", "agents", "quality"]},
84
+ {"id": 29, "name": "evolva-codebase-memory-mcp", "layer": 5, "description": "MCP server providing codebase memory and knowledge graph access", "language": "Python", "stars": 35, "topics": ["mcp", "codebase", "memory"]},
85
+ {"id": 30, "name": "evolva-mcp-registry", "layer": 5, "description": "Registry and discovery service for MCP servers", "language": "Python", "stars": 20, "topics": ["mcp", "registry", "discovery"]},
86
+ {"id": 31, "name": "evolva-api-gateway", "layer": 5, "description": "API gateway with rate limiting, auth, and routing", "language": "Python", "stars": 16, "topics": ["api-gateway", "fastapi", "routing"]},
87
+ {"id": 32, "name": "evolva-webhook-handler", "layer": 5, "description": "Webhook processing and event dispatch system", "language": "Python", "stars": 9, "topics": ["webhooks", "events", "async"]},
88
+ {"id": 33, "name": "evolva-connector-sdk", "layer": 5, "description": "SDK for building custom connectors and integrations", "language": "Python", "stars": 13, "topics": ["sdk", "connectors", "integrations"]},
89
+ {"id": 34, "name": "evolva-integration-hub", "layer": 5, "description": "Central hub for third-party service integrations", "language": "Python", "stars": 11, "topics": ["integrations", "hub", "connectors"]},
90
+ {"id": 35, "name": "evolva-oauth-provider", "layer": 5, "description": "OAuth 2.0 provider and identity management service", "language": "Python", "stars": 8, "topics": ["oauth", "auth", "identity"]},
91
+ {"id": 36, "name": "ttruthdesk-platform", "layer": 6, "description": "Truth desk platform for fact-checking and citation verification", "language": "TypeScript", "stars": 42, "topics": ["fact-checking", "citations", "platform"]},
92
+ {"id": 37, "name": "evolva-dashboard", "layer": 6, "description": "Main analytics and monitoring dashboard", "language": "TypeScript", "stars": 19, "topics": ["dashboard", "analytics", "react"]},
93
+ {"id": 38, "name": "evolva-web-app", "layer": 6, "description": "Primary web application with full-stack React/FastAPI", "language": "TypeScript", "stars": 27, "topics": ["web-app", "react", "fastapi"]},
94
+ {"id": 39, "name": "evolva-api-server", "layer": 6, "description": "Main REST/GraphQL API server", "language": "Python", "stars": 23, "topics": ["api", "rest", "graphql"]},
95
+ {"id": 40, "name": "evolva-admin-panel", "layer": 6, "description": "Administrative panel for system management", "language": "TypeScript", "stars": 11, "topics": ["admin", "management", "dashboard"]},
96
+ {"id": 41, "name": "evolva-docs-site", "layer": 6, "description": "Documentation website and developer portal", "language": "Markdown", "stars": 15, "topics": ["docs", "documentation", "developer-portal"]},
97
+ {"id": 42, "name": "evolva-landing-page", "layer": 6, "description": "Marketing landing page and product showcase", "language": "TypeScript", "stars": 8, "topics": ["landing-page", "marketing", "nextjs"]},
98
+ {"id": 43, "name": "evolva-research-lab", "layer": 7, "description": "Research experiments and novel AI technique exploration", "language": "Python", "stars": 33, "topics": ["research", "experiments", "ai"]},
99
+ {"id": 44, "name": "evolva-experiments", "layer": 7, "description": "Feature experiments and A/B testing framework", "language": "Python", "stars": 14, "topics": ["experiments", "ab-testing", "features"]},
100
+ {"id": 45, "name": "evolva-benchmarks", "layer": 7, "description": "Performance and quality benchmarking suite", "language": "Python", "stars": 18, "topics": ["benchmarks", "performance", "quality"]},
101
+ {"id": 46, "name": "evolva-prototypes", "layer": 7, "description": "Rapid prototyping and proof-of-concept implementations", "language": "Python", "stars": 9, "topics": ["prototypes", "poc", "innovation"]},
102
+ {"id": 47, "name": "evolva-papers", "layer": 7, "description": "Research papers, technical reports, and academic contributions", "language": "LaTeX", "stars": 22, "topics": ["papers", "research", "academic"]},
103
+ {"id": 48, "name": "evolva-datasets", "layer": 7, "description": "Curated datasets for training and evaluation", "language": "Python", "stars": 16, "topics": ["datasets", "data", "training"]},
104
+ {"id": 49, "name": "evolva-notebooks", "layer": 7, "description": "Jupyter notebooks for analysis and exploration", "language": "Jupyter", "stars": 20, "topics": ["notebooks", "jupyter", "analysis"]},
105
+ {"id": 50, "name": "evolva-roadmap", "layer": 7, "description": "Product roadmap, milestones, and strategic planning", "language": "Markdown", "stars": 11, "topics": ["roadmap", "planning", "strategy"]},
106
+ {"id": 51, "name": "evolva-sdk-python", "layer": 5, "description": "Official Python SDK for the Evolva platform", "language": "Python", "stars": 38, "topics": ["sdk", "python", "client"]},
107
+ {"id": 52, "name": "evolva-sdk-typescript", "layer": 5, "description": "Official TypeScript/JavaScript SDK for the Evolva platform", "language": "TypeScript", "stars": 29, "topics": ["sdk", "typescript", "client"]},
108
+ {"id": 53, "name": "evolva-cli", "layer": 5, "description": "Command-line interface for Evolva platform management", "language": "Python", "stars": 24, "topics": ["cli", "devtools", "management"]},
109
+ {"id": 54, "name": "evolva-plugin-system", "layer": 5, "description": "Plugin architecture and extension system for Evolva", "language": "Python", "stars": 17, "topics": ["plugins", "extensions", "architecture"]}
110
+ ],
111
+ "relationships": [
112
+ {"from": "evolva-agent-core", "to": "evolva-llm-core", "type": "depends_on"},
113
+ {"from": "evolva-agent-core", "to": "evolva-agent-memory", "type": "depends_on"},
114
+ {"from": "evolva-agent-core", "to": "evolva-agent-tools", "type": "depends_on"},
115
+ {"from": "evolva-agent-orchestrator", "to": "evolva-agent-core", "type": "depends_on"},
116
+ {"from": "evolva-codebase-memory-mcp", "to": "evolva-knowledge-graph", "type": "depends_on"},
117
+ {"from": "evolva-codebase-memory-mcp", "to": "evolva-vector-store", "type": "depends_on"},
118
+ {"from": "evolva-codebase-memory-mcp", "to": "evolva-agent-memory", "type": "depends_on"},
119
+ {"from": "ttruthdesk-platform", "to": "evolva-api-server", "type": "depends_on"},
120
+ {"from": "ttruthdesk-platform", "to": "evolva-agent-core", "type": "depends_on"},
121
+ {"from": "evolva-inference-engine", "to": "evolva-llm-core", "type": "depends_on"},
122
+ {"from": "evolva-api-gateway", "to": "evolva-oauth-provider", "type": "depends_on"},
123
+ {"from": "evolva-web-app", "to": "evolva-api-gateway", "type": "depends_on"},
124
+ {"from": "manus-persistent-drive", "to": "evolva-db-core", "type": "depends_on"},
125
+ {"from": "evolva-sdk-python", "to": "evolva-api-gateway", "type": "depends_on"},
126
+ {"from": "evolva-sdk-typescript", "to": "evolva-api-gateway", "type": "depends_on"},
127
+ {"from": "evolva-cli", "to": "evolva-sdk-python", "type": "depends_on"},
128
+ {"from": "evolva-plugin-system", "to": "evolva-agent-core", "type": "depends_on"}
129
+ ]
130
+ }
mcp_server/requirements.txt ADDED
@@ -0,0 +1,4 @@
 
 
 
 
 
1
+ fastapi==0.111.0
2
+ uvicorn[standard]==0.30.1
3
+ python-multipart==0.0.9
4
+ httpx==0.27.0
mcp_server/server.py ADDED
@@ -0,0 +1,383 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Evolva Codebase Memory MCP Server
3
+ FastAPI server exposing 6 MCP tools for codebase knowledge graph access.
4
+ Serves 54 indexed repositories across a 7-layer architecture.
5
+ """
6
+
7
+ import json
8
+ import os
9
+ from pathlib import Path
10
+ from typing import Any, Dict, List, Optional
11
+
12
+ from fastapi import FastAPI, HTTPException, Query
13
+ from fastapi.middleware.cors import CORSMiddleware
14
+ from fastapi.responses import JSONResponse
15
+ from fastapi.staticfiles import StaticFiles
16
+
17
+ # ── App setup ──────────────────────────────────────────────────────────────────
18
+ app = FastAPI(
19
+ title="Evolva Codebase Memory MCP",
20
+ description="MCP server providing codebase memory and knowledge graph access for 54 Evolva repositories",
21
+ version="1.0.0",
22
+ docs_url="/api/docs",
23
+ redoc_url="/api/redoc",
24
+ )
25
+
26
+ app.add_middleware(
27
+ CORSMiddleware,
28
+ allow_origins=["*"],
29
+ allow_credentials=True,
30
+ allow_methods=["*"],
31
+ allow_headers=["*"],
32
+ )
33
+
34
+ # ── Load knowledge graph ───────────────────────────────────────────────────────
35
+ KG_PATH = Path(__file__).parent.parent / "kg" / "knowledge_graph.json"
36
+
37
+ def load_kg() -> Dict[str, Any]:
38
+ with open(KG_PATH, "r") as f:
39
+ return json.load(f)
40
+
41
+ KG = load_kg()
42
+
43
+ # ── Mount static docs ──────────────────────────────────────────────────────────
44
+ DOCS_PATH = Path(__file__).parent.parent / "docs"
45
+ if DOCS_PATH.exists():
46
+ app.mount("/docs", StaticFiles(directory=str(DOCS_PATH), html=True), name="docs")
47
+
48
+ # ── Health endpoint ────────────────────────────────────────────────────────────
49
+ @app.get("/health")
50
+ async def health():
51
+ """Health check endpoint."""
52
+ return {
53
+ "status": "up",
54
+ "repos_indexed": KG["metadata"]["total_repos"],
55
+ "version": KG["metadata"]["version"],
56
+ "layers": KG["metadata"]["total_layers"],
57
+ }
58
+
59
+ # ── MCP Tool definitions ───────────────────────────────────────────────────────
60
+ MCP_TOOLS = [
61
+ {
62
+ "name": "search_repos",
63
+ "description": "Search repositories by name, topic, language, or layer. Returns matching repos with metadata.",
64
+ "inputSchema": {
65
+ "type": "object",
66
+ "properties": {
67
+ "query": {"type": "string", "description": "Search query (name, topic, or language)"},
68
+ "layer": {"type": "integer", "description": "Filter by architecture layer (1-7)", "minimum": 1, "maximum": 7},
69
+ "language": {"type": "string", "description": "Filter by programming language"},
70
+ "limit": {"type": "integer", "description": "Max results to return", "default": 10},
71
+ },
72
+ "required": ["query"],
73
+ },
74
+ },
75
+ {
76
+ "name": "get_repo_details",
77
+ "description": "Get detailed information about a specific repository including dependencies and relationships.",
78
+ "inputSchema": {
79
+ "type": "object",
80
+ "properties": {
81
+ "repo_name": {"type": "string", "description": "Repository name to look up"},
82
+ },
83
+ "required": ["repo_name"],
84
+ },
85
+ },
86
+ {
87
+ "name": "get_architecture",
88
+ "description": "Get the full 7-layer architecture overview with all repositories organized by layer.",
89
+ "inputSchema": {
90
+ "type": "object",
91
+ "properties": {
92
+ "layer_id": {"type": "integer", "description": "Optional: get details for a specific layer (1-7)", "minimum": 1, "maximum": 7},
93
+ },
94
+ },
95
+ },
96
+ {
97
+ "name": "get_dependencies",
98
+ "description": "Get dependency graph for a repository — what it depends on and what depends on it.",
99
+ "inputSchema": {
100
+ "type": "object",
101
+ "properties": {
102
+ "repo_name": {"type": "string", "description": "Repository name to get dependencies for"},
103
+ "direction": {"type": "string", "enum": ["upstream", "downstream", "both"], "default": "both"},
104
+ },
105
+ "required": ["repo_name"],
106
+ },
107
+ },
108
+ {
109
+ "name": "get_stats",
110
+ "description": "Get aggregate statistics about the codebase: language distribution, layer sizes, star counts, topic frequency.",
111
+ "inputSchema": {
112
+ "type": "object",
113
+ "properties": {
114
+ "metric": {"type": "string", "enum": ["languages", "layers", "stars", "topics", "all"], "default": "all"},
115
+ },
116
+ },
117
+ },
118
+ {
119
+ "name": "find_related",
120
+ "description": "Find repositories related to a given repo based on shared topics, language, layer proximity, or dependency graph.",
121
+ "inputSchema": {
122
+ "type": "object",
123
+ "properties": {
124
+ "repo_name": {"type": "string", "description": "Repository name to find related repos for"},
125
+ "strategy": {"type": "string", "enum": ["topics", "language", "layer", "dependencies", "all"], "default": "all"},
126
+ "limit": {"type": "integer", "description": "Max results to return", "default": 5},
127
+ },
128
+ "required": ["repo_name"],
129
+ },
130
+ },
131
+ ]
132
+
133
+ # ── MCP endpoints ──────────────────────────────────────────────────────────────
134
+ @app.get("/mcp/tools")
135
+ async def list_tools():
136
+ """Return all 6 MCP tool definitions."""
137
+ return {
138
+ "tools": MCP_TOOLS,
139
+ "count": len(MCP_TOOLS),
140
+ "server": "evolva-codebase-memory-mcp",
141
+ "version": "1.0.0",
142
+ }
143
+
144
+ @app.post("/mcp/call")
145
+ async def call_tool(body: Dict[str, Any]):
146
+ """Execute an MCP tool call."""
147
+ tool_name = body.get("name")
148
+ args = body.get("arguments", {})
149
+
150
+ if tool_name == "search_repos":
151
+ return await _search_repos(args)
152
+ elif tool_name == "get_repo_details":
153
+ return await _get_repo_details(args)
154
+ elif tool_name == "get_architecture":
155
+ return await _get_architecture(args)
156
+ elif tool_name == "get_dependencies":
157
+ return await _get_dependencies(args)
158
+ elif tool_name == "get_stats":
159
+ return await _get_stats(args)
160
+ elif tool_name == "find_related":
161
+ return await _find_related(args)
162
+ else:
163
+ raise HTTPException(status_code=404, detail=f"Tool '{tool_name}' not found")
164
+
165
+ # ── REST API endpoints ─────────────────────────────────────────────────────────
166
+ @app.get("/v1/repos")
167
+ async def list_repos(
168
+ layer: Optional[int] = Query(None, ge=1, le=7),
169
+ language: Optional[str] = None,
170
+ topic: Optional[str] = None,
171
+ ):
172
+ """Return all 54 repositories with optional filters."""
173
+ repos = KG["repositories"]
174
+ if layer:
175
+ repos = [r for r in repos if r["layer"] == layer]
176
+ if language:
177
+ repos = [r for r in repos if r["language"].lower() == language.lower()]
178
+ if topic:
179
+ repos = [r for r in repos if topic.lower() in [t.lower() for t in r.get("topics", [])]]
180
+ return {
181
+ "repos": repos,
182
+ "count": len(repos),
183
+ "total": KG["metadata"]["total_repos"],
184
+ }
185
+
186
+ @app.get("/v1/repos/{repo_name}")
187
+ async def get_repo(repo_name: str):
188
+ """Get a specific repository by name."""
189
+ repos = KG["repositories"]
190
+ repo = next((r for r in repos if r["name"].lower() == repo_name.lower()), None)
191
+ if not repo:
192
+ raise HTTPException(status_code=404, detail=f"Repository '{repo_name}' not found")
193
+ # Enrich with relationships
194
+ relationships = KG.get("relationships", [])
195
+ upstream = [r["to"] for r in relationships if r["from"] == repo["name"]]
196
+ downstream = [r["from"] for r in relationships if r["to"] == repo["name"]]
197
+ return {**repo, "depends_on": upstream, "depended_by": downstream}
198
+
199
+ @app.get("/v1/architecture")
200
+ async def get_architecture_endpoint(layer_id: Optional[int] = Query(None, ge=1, le=7)):
201
+ """Return the 7-layer architecture."""
202
+ layers = KG["architecture"]["layers"]
203
+ if layer_id:
204
+ layer = next((l for l in layers if l["id"] == layer_id), None)
205
+ if not layer:
206
+ raise HTTPException(status_code=404, detail=f"Layer {layer_id} not found")
207
+ return layer
208
+ return {
209
+ "layers": layers,
210
+ "total_layers": len(layers),
211
+ "total_repos": KG["metadata"]["total_repos"],
212
+ }
213
+
214
+ @app.get("/v1/stats")
215
+ async def get_stats_endpoint():
216
+ """Return aggregate statistics."""
217
+ repos = KG["repositories"]
218
+ languages: Dict[str, int] = {}
219
+ topics: Dict[str, int] = {}
220
+ layer_counts: Dict[int, int] = {}
221
+ total_stars = 0
222
+
223
+ for repo in repos:
224
+ lang = repo.get("language", "Unknown")
225
+ languages[lang] = languages.get(lang, 0) + 1
226
+ for t in repo.get("topics", []):
227
+ topics[t] = topics.get(t, 0) + 1
228
+ layer = repo.get("layer", 0)
229
+ layer_counts[layer] = layer_counts.get(layer, 0) + 1
230
+ total_stars += repo.get("stars", 0)
231
+
232
+ return {
233
+ "total_repos": len(repos),
234
+ "total_stars": total_stars,
235
+ "languages": languages,
236
+ "layer_distribution": layer_counts,
237
+ "top_topics": dict(sorted(topics.items(), key=lambda x: x[1], reverse=True)[:20]),
238
+ }
239
+
240
+ @app.get("/v1/relationships")
241
+ async def get_relationships():
242
+ """Return all repository relationships."""
243
+ return {
244
+ "relationships": KG.get("relationships", []),
245
+ "count": len(KG.get("relationships", [])),
246
+ }
247
+
248
+ # ── Tool implementations ───────────────────────────────────────────────────────
249
+ async def _search_repos(args: Dict[str, Any]) -> Dict[str, Any]:
250
+ query = args.get("query", "").lower()
251
+ layer = args.get("layer")
252
+ language = args.get("language", "").lower()
253
+ limit = args.get("limit", 10)
254
+ repos = KG["repositories"]
255
+ results = []
256
+ for repo in repos:
257
+ score = 0
258
+ if query in repo["name"].lower():
259
+ score += 3
260
+ if query in repo.get("description", "").lower():
261
+ score += 2
262
+ if any(query in t.lower() for t in repo.get("topics", [])):
263
+ score += 2
264
+ if layer and repo["layer"] == layer:
265
+ score += 1
266
+ if language and repo.get("language", "").lower() == language:
267
+ score += 1
268
+ if score > 0:
269
+ results.append({**repo, "_score": score})
270
+ results.sort(key=lambda x: x["_score"], reverse=True)
271
+ return {"results": results[:limit], "count": len(results[:limit]), "query": query}
272
+
273
+ async def _get_repo_details(args: Dict[str, Any]) -> Dict[str, Any]:
274
+ repo_name = args.get("repo_name", "")
275
+ repos = KG["repositories"]
276
+ repo = next((r for r in repos if r["name"].lower() == repo_name.lower()), None)
277
+ if not repo:
278
+ return {"error": f"Repository '{repo_name}' not found", "available_repos": [r["name"] for r in repos[:10]]}
279
+ relationships = KG.get("relationships", [])
280
+ upstream = [r["to"] for r in relationships if r["from"] == repo["name"]]
281
+ downstream = [r["from"] for r in relationships if r["to"] == repo["name"]]
282
+ layer_info = next((l for l in KG["architecture"]["layers"] if l["id"] == repo["layer"]), {})
283
+ return {**repo, "depends_on": upstream, "depended_by": downstream, "layer_info": layer_info}
284
+
285
+ async def _get_architecture(args: Dict[str, Any]) -> Dict[str, Any]:
286
+ layer_id = args.get("layer_id")
287
+ layers = KG["architecture"]["layers"]
288
+ if layer_id:
289
+ layer = next((l for l in layers if l["id"] == layer_id), None)
290
+ if not layer:
291
+ return {"error": f"Layer {layer_id} not found"}
292
+ repos_in_layer = [r for r in KG["repositories"] if r["layer"] == layer_id]
293
+ return {**layer, "repositories": repos_in_layer}
294
+ return {"layers": layers, "total_layers": len(layers), "total_repos": KG["metadata"]["total_repos"]}
295
+
296
+ async def _get_dependencies(args: Dict[str, Any]) -> Dict[str, Any]:
297
+ repo_name = args.get("repo_name", "")
298
+ direction = args.get("direction", "both")
299
+ relationships = KG.get("relationships", [])
300
+ result: Dict[str, Any] = {"repo": repo_name}
301
+ if direction in ("upstream", "both"):
302
+ result["depends_on"] = [r["to"] for r in relationships if r["from"] == repo_name]
303
+ if direction in ("downstream", "both"):
304
+ result["depended_by"] = [r["from"] for r in relationships if r["to"] == repo_name]
305
+ return result
306
+
307
+ async def _get_stats(args: Dict[str, Any]) -> Dict[str, Any]:
308
+ metric = args.get("metric", "all")
309
+ repos = KG["repositories"]
310
+ languages: Dict[str, int] = {}
311
+ topics: Dict[str, int] = {}
312
+ layer_counts: Dict[int, int] = {}
313
+ total_stars = 0
314
+ for repo in repos:
315
+ lang = repo.get("language", "Unknown")
316
+ languages[lang] = languages.get(lang, 0) + 1
317
+ for t in repo.get("topics", []):
318
+ topics[t] = topics.get(t, 0) + 1
319
+ layer = repo.get("layer", 0)
320
+ layer_counts[layer] = layer_counts.get(layer, 0) + 1
321
+ total_stars += repo.get("stars", 0)
322
+ if metric == "languages":
323
+ return {"languages": languages}
324
+ elif metric == "layers":
325
+ return {"layer_distribution": layer_counts}
326
+ elif metric == "stars":
327
+ return {"total_stars": total_stars, "avg_stars": round(total_stars / len(repos), 1)}
328
+ elif metric == "topics":
329
+ return {"topics": dict(sorted(topics.items(), key=lambda x: x[1], reverse=True)[:20])}
330
+ return {
331
+ "total_repos": len(repos),
332
+ "total_stars": total_stars,
333
+ "avg_stars": round(total_stars / len(repos), 1),
334
+ "languages": languages,
335
+ "layer_distribution": layer_counts,
336
+ "top_topics": dict(sorted(topics.items(), key=lambda x: x[1], reverse=True)[:20]),
337
+ }
338
+
339
+ async def _find_related(args: Dict[str, Any]) -> Dict[str, Any]:
340
+ repo_name = args.get("repo_name", "")
341
+ strategy = args.get("strategy", "all")
342
+ limit = args.get("limit", 5)
343
+ repos = KG["repositories"]
344
+ target = next((r for r in repos if r["name"].lower() == repo_name.lower()), None)
345
+ if not target:
346
+ return {"error": f"Repository '{repo_name}' not found"}
347
+ scores: Dict[str, float] = {}
348
+ for repo in repos:
349
+ if repo["name"] == target["name"]:
350
+ continue
351
+ score = 0.0
352
+ if strategy in ("topics", "all"):
353
+ shared = set(target.get("topics", [])) & set(repo.get("topics", []))
354
+ score += len(shared) * 2
355
+ if strategy in ("language", "all"):
356
+ if repo.get("language") == target.get("language"):
357
+ score += 1
358
+ if strategy in ("layer", "all"):
359
+ layer_diff = abs(repo["layer"] - target["layer"])
360
+ if layer_diff == 0:
361
+ score += 2
362
+ elif layer_diff == 1:
363
+ score += 1
364
+ if strategy in ("dependencies", "all"):
365
+ relationships = KG.get("relationships", [])
366
+ if any(r["from"] == target["name"] and r["to"] == repo["name"] for r in relationships):
367
+ score += 3
368
+ if any(r["from"] == repo["name"] and r["to"] == target["name"] for r in relationships):
369
+ score += 3
370
+ if score > 0:
371
+ scores[repo["name"]] = score
372
+ ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)[:limit]
373
+ related = []
374
+ for name, score in ranked:
375
+ repo = next(r for r in repos if r["name"] == name)
376
+ related.append({**repo, "_relevance_score": score})
377
+ return {"repo": repo_name, "related": related, "strategy": strategy}
378
+
379
+ # ── Entry point ────────────────────────────────────────────────────────────────
380
+ if __name__ == "__main__":
381
+ import uvicorn
382
+ port = int(os.environ.get("PORT", 7860))
383
+ uvicorn.run(app, host="0.0.0.0", port=port)