Arc helps engineering teams understand the context and history behind their code. This MCP server lets AI assistants query your codebase s history and relationships using natural language.
"Why did we choose MongoDB over PostgreSQL?"
"How did the authentication system evolve over time?"
"What was the rationale behind the microservices architecture?"
Quick Start Workflow
- Install dependencies
pip install mcp arc-memory
- Authenticate with GitHub
arc auth gh
This will guide you through authenticating with GitHub. You ll see a success message when complete.
- Authenticate with Linear (Optional)
arc auth linear
This will guide you through authenticating with Linear using OAuth 2.0. A browser window will open for you to authorize Arc Memory to access your Linear data. This step is optional but recommended if you want to include Linear issues in your knowledge graph.
- Build your knowledge graph
arc build
This will analyze your repository and build a local knowledge graph. You ll see progress indicators and a summary of ingested entities when complete.
To include Linear issues in your knowledge graph:
arc build --linear
This requires Linear authentication (step 3).
- Configure in Claude Desktop, VS Code Agent Mode, or Cursor
See the "Integration" section below for detailed instructions.
How Arc Works
Arc builds a graph of your codebase s history, connecting structured data from different sources. Instead of using vector similarity like typical RAG systems, Arc focuses on the actual relationships between commits, PRs, issues, and architectural decisions.
The arc_search_story tool converts natural language questions into graph queries that can follow multiple connections, helping AI assistants provide answers based on your project s actual history.
Knowledge Graph Structure
Arc builds a rich knowledge graph with:
- Entities: PRs, commits, issues (GitHub & Linear), ADRs, files, and more
- Relationships: MODIFIES, MENTIONS, MERGES, DECIDES, IMPLEMENTS
- Temporal context: When changes happened and in what sequence
- Provenance: Why changes were made and who made them
- Cross-system connections: Links between GitHub PRs and Linear issues
This interconnected structure enables tracing the complete story behind any line of code—from the initial issue, through architectural decisions, to implementation PRs and commits.
For example, a typical path might look like:
Linear Issue ABC-123 (Feature Request)
↓ DECIDES
Architecture Decision Record (ADR-42)
↓ IMPLEMENTS
GitHub Pull Request #456
↓ CONTAINS
Commit abc123
↓ MODIFIES
File: src/auth/middleware.js
When you ask "Why was the authentication middleware implemented this way?", Arc can traverse this path backward to provide the complete context.
Connecting Different Systems
Using GitHub and Linear MCPs separately works for basic queries, but Arc connects them together:
- Connected Data: Links information from GitHub, Linear, Git, and ADRs in one graph
- Cross-system Connections: Shows relationships between Linear issues and GitHub PRs
- Multi-step Paths: Follows chains of connections that separate API calls would miss
- Time-based Context: Maintains when things happened across different systems
- Structured Results: Returns paths that AI assistants can use to explain relationships
Example Questions
Architectural Reasoning & Decision Archaeology
"What were the security considerations that led to our current authentication architecture?"
"Why did we migrate from monolith to microservices in Q3 2022, and what were the tradeoffs?"
"What performance issues drove the switch from Redis to our custom caching solution?"
"How did our API design evolve after the major outage last year?"
Cross-System Impact Analysis
"Which backend services were affected by the payment processing refactoring?"
"What downstream components depend on the authentication middleware we re planning to change?"
"How many different teams code would be impacted if we deprecate the legacy API?"
"What parts of our infrastructure were modified to address the rate limiting issues?"
Technical Debt & Regression Prevention
"What previous attempts have we made to fix the intermittent test failures in the CI pipeline?"
"Which PRs have touched this fragile payment processing code in the last 6 months?"
"What was the root cause analysis of our last three production incidents?"
"Which architectural decisions have we revisited multiple times, suggesting design instability?"
Knowledge Transfer & Onboarding
"What s the complete history of our authentication system from initial design to current implementation?"
"Who are the domain experts for each component of our data processing pipeline?"
"What were the key design decisions made before I joined the team that explain our current architecture?"
"What s the context behind this complex caching logic that no one seems to understand anymore?"
- arc_search_story: Natural-language graph query for multi-hop questions
- arc_trace_history: Traces the decision history for a specific line in a file
- arc_get_entity_details: Retrieves detailed information about a specific entity
- arc_find_related_entities: Finds entities directly connected to a given entity
- arc_blame_line: Gets the specific commit SHA, author, and date for a line
Installation
# Install dependencies
pip install mcp arc-memory
# Clone the repository
git clone https://github.com/Arc-Computer/arc-mcp-server.git
cd arc-mcp-server
# Install the server
pip install -e .
Setup
-
Authenticate with GitHub (if you have GitHub OAuth credentials)
arc auth gh
-
Build your knowledge graph
arc build
This builds a graph from your local Git repository, including commits, files, PRs, issues, and their relationships. The database is stored at ~/.arc/graph.db.
Integration
Claude Desktop
- Open your configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
-
Windows: %APPDATA%Claudeclaude_desktop_config.json
-
Add the server configuration:
{
"mcpServers": {
"arc-memory": {
"command": "python",
"args": ["/absolute/path/to/src/arc_mcp_server.py"]
}
}
}
-
Restart Claude Desktop
VS Code Agent Mode
-
Install the VS Code Agent Mode extension
-
Configure the MCP server in your VS Code settings:
"anthropic.agent-mode.mcp.servers": {
"arc-memory": {
"command": "python",
"args": ["/absolute/path/to/src/arc_mcp_server.py"]
}
}
Cursor
- Open Cursor settings and navigate to the AI settings
- Configure the MCP server (similar to VS Code configuration)
- Restart Cursor
arc_search_story
Natural-language graph query for multi-hop questions.
Parameters:
- question: The natural language question to ask
- max_depth (optional): Maximum depth for graph traversal (default: 3)
- max_results (optional): Maximum number of results to return (default: 100)
Returns:
{
"path": [
{"id": "pr:42", "type": "pr", "title": "Add new feature", "depth": 0},
{"id": "adr:123", "type": "adr", "title": "Architecture decision", "depth": 1},
{"id": "issue:456", "type": "issue", "title": "Feature request", "depth": 2}
],
"meta": {
"query_depth": 3,
"sql": "/* The SQL query used for debugging */"
}
}
How AI Assistants Use This Data
When a developer asks "Why did we migrate from Redis to our custom caching solution?", the AI assistant can use the structured path data to create a response like:
"The migration from Redis to our custom caching solution in July 2023 was driven by three key factors:
-
Performance bottlenecks: Linear issue PERF-387 documented Redis connection pooling problems during peak traffic, causing 30% of the latency spikes observed in Q2 2023. This was prioritized as P0 by the Platform team after the June outage.
-
Architectural limitations: ADR-29 (authored by Sarah Chen) details how Redis s single-threaded model couldn t efficiently handle our growing concurrent write patterns, particularly for the product catalog service. This ADR references Linear issue ARCH-42 where the initial concerns were raised.
-
Cost considerations: GitHub PR #1204 included benchmark results showing the custom solution reduced infrastructure costs by 42% while improving p99 latency by 150ms. This PR was linked to Linear issue COST-56 from the Q3 cost optimization initiative.
The migration was implemented across 7 GitHub PRs, primarily by the Infrastructure team, with the most significant changes in the inventory and checkout services. There were initial concerns about data consistency (raised by Alex Kim in PR #1209), which were addressed by adding the two-phase commit protocol documented in ADR-31.
The custom solution has been stable since deployment, with only two minor incidents (tracked in Linear as INC-45 and INC-52) related to cache invalidation edge cases, both resolved in follow-up GitHub PR #1567."
The response includes:
- Information from different sources (Linear issues, GitHub PRs, ADRs, incidents)
- Specific metrics and measurements
- Names of people involved and their roles
- The sequence of events and technical details
- Problems that came up and their solutions
- What happened afterward
This works because Arc connects information across different systems that would normally be separate.
Common Use Cases
1. Onboarding New Team Members
When new developers join a team, they can ask questions about unfamiliar code and systems to understand the context and reasoning behind implementations.
2. Preventing Regressions
Before making changes to complex or critical systems, developers can explore the history of previous issues, approaches that didn t work, and the reasoning behind the current implementation.
3. Making Architectural Decisions
When considering changes to the architecture, teams can look at the history of related decisions, understanding what was tried before and why certain approaches were chosen.
4. Refactoring Legacy Code
When working with older code that lacks documentation, developers can trace its origins, understand its purpose, and identify its dependencies before making changes.
Future Development
Future plans for Arc include:
- Running lightweight simulations on PRs to identify potential issues
- Detecting security vulnerabilities and technical debt risks
- Building a causal model of system behavior over time
- Adding the simulation results back into the knowledge graph
License
MIT License
Need Help?