# Cross-Project MCP Server

A generic MCP (Model Context Protocol) server that allows AI agents to access code from another project. This enables agents working in one repository (e.g., your website) to reference implementation details from a source repository (e.g., your OSS tool).

## Discovery & Instructions

The server exposes `get_agent_instructions` to help agents understand the target repository.

- **Best Practice**: Agents should call `get_agent_instructions` first to read `.agent/gemini.md` (or similar) from the source repo. This provides context on *when* and *how* to delegate tasks.

## Tools Reference

### Code Exploration

| Tool | Description |
|------|-------------|
| `read_file` | Read file contents with optional line ranges |
| `list_directory` | Browse directory structure (recursive optional) |
| `search_code` | Search for patterns (regex or literal) across the codebase |
| `get_file_outline` | Extract functions, classes, and symbols from source files |
| `find_files` | Find files by name pattern (glob matching) |

### Agent Discovery & Delegation

| Tool | Description |
|------|-------------|
| `get_agent_instructions` | Read `.agent/gemini.md` to understand the repo's purpose and rules |
| `submit_task` | Delegate work by creating a task file in `.agent/tasks/` |
| `list_tasks` | List tasks in the inbox, filterable by status (OPEN, IN_PROGRESS, DONE, BLOCKED) |
| `read_task` | Read the full content of a specific task file |

All operations are sandboxed to the configured source project path for security.

## Installation

```bash
cd cross-project-mcp-server
npm install
npm run build
```

## Configuration for Antigravity

Add the server to your project's `.gemini/mcp_settings.json`:

```json
{
  "mcpServers": {
    "oss-project": {
      "command": "node",
      "args": [
        "/absolute/path/to/cross-project-mcp-server/dist/index.js",
        "/absolute/path/to/your-oss-repo"
      ]
    }
  }
}
```

### Configuration Parameters

| Parameter | Description |
|-----------|-------------|
| `"oss-project"` | A descriptive name for your source project (can be anything) |
| First arg | Path to this server's `dist/index.js` |
| Second arg | Path to your OSS/source repository |

### Example

If your OSS tool is at `/Users/you/projects/my-oss-tool` and this server is at `/Users/you/tools/cross-project-mcp-server`:

```json
{
  "mcpServers": {
    "my-oss-tool": {
      "command": "node",
      "args": [
        "/Users/you/tools/cross-project-mcp-server/dist/index.js",
        "/Users/you/projects/my-oss-tool"
      ]
    }
  }
}
```

## Usage

Once configured, the MCP tools will be available to AI agents working in your project. The agent can:

1. **Explore structure**: List directories, find files by pattern
2. **Read implementation**: Read specific files or line ranges
3. **Search code**: Find usages of functions, types, or patterns
4. **Understand symbols**: Get outlines of classes and functions

## Supported Languages for Outline

The `get_file_outline` tool supports extracting symbols from:

- TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`)
- Python (`.py`)
- Java/Kotlin (`.java`, `.kt`)
- Go (`.go`)
- Rust (`.rs`)

## Security

- All file access is restricted to the configured source project directory
- Common non-essential directories (node_modules, .git, etc.) are automatically excluded
- Path traversal attempts are blocked

## Task Delegation (Multi-Agent)

This server supports a **Task Delegation Protocol** allowing agents to request work from the repository owner.

- **submit_task**: Write a structured task request (Markdown) to `.agent/tasks/`
- **list_tasks**: Check the inbox for new requests
- **read_task**: Read the full context of a request

### Workflow
1. Agent A (Website) needs a change in Repo B (OSS).
2. Agent A calls `submit_task` on Repo B's MCP server.
3. A file `task_[timestamp]_[title].md` is created in Repo B.
4. Agent B (OSS) sees the task and implements it.