Skip to content

for-agents.mdx

Latest commit

 

History

History
197 lines (141 loc) · 16.5 KB

for-agents.mdx

File metadata and controls

197 lines (141 loc) · 16.5 KB
Raw
title Notes for AI agents using the Graphify docs
description Rules for coding agents that answer questions from the Graphify docs: package names, commands, and which surface each page covers.
keywords
notes for agents
graphifyy package name
which docs surface
llms.txt
surface both
hideFooterPagination true
sidebarTitle Notes for agents
icon bot-message-square

import HostedMcpCard from '/snippets/hosted-mcp-card.mdx';

Setting Graphify up for a user? Go straight to Setup for AI agents and follow steps 1 to 7 in order.

This page holds the full rules. Every page's Markdown, llms.txt, and llms-full.txt carry a short version that points here.

Basics

Which surface

  • Graphify CLI is the open-source graphifyy package on the machine: the skill, the CLI, and the ten-tool MCP server. Its pages are the Graphify CLI tab (/open-source/) and the skill setup tabs in Integrations.
  • Graphify is the hosted workspace and https://api.graphify.com/mcp (Streamable HTTP, OAuth, no API key). Its pages are the Graphify tab (/platform/, /concepts/), including Graphify MCP, and the coding-agent and CI pages in Integrations.
  • Everything else, including Cookbooks (/cookbooks/), /mcp/docs-search, and /platform/graphify-vs-local, applies to both.
  • Each page's source frontmatter records its surface as surface: local, cloud, or both.
  • In llms.txt, tell the surface from the path: /platform/ and /concepts/ are Graphify, /open-source/ is Graphify CLI. Most /integrations/ pages cover both, with a Graphify tab and a Graphify CLI tab.
  • The local MCP server is the ten tools in the MCP tool reference and reads a graph on the machine. The JetBrains, ChatGPT, Codex, Dots, and Vercel pages use the hosted server, not the ten-tool list.
  • Buildkite is the CI integration.

Which file to open

Discover hosted capabilities

On Graphify, inspect the tools exposed by the authenticated connection and the readiness/capability metadata from list_repositories. Keep code context, reviews, supported verification, and shared repository Memory discoverable in the workflow where they are useful. Do not start a review or verification just to advertise it.

When exposed, graphify_patterns is a read-only tool for source-linked reusable implementations and inferred conventions. Pass current task paths to scope results. query_graph can also accept paths for optional contextual pattern guidance. Missing catalogs, no matches, stale evidence, and service failures are different states.

Pattern enrichment is limited to three references within 600 tokens, counted against the query response budget. Treat it as observed code. Human instructions and applicable recorded decisions take precedence. Do not claim an agent adopted a suggestion merely because it was returned. Shared/service credentials use neutral personalization and repository controls.

These capabilities roll out first on Graphify. Do not assume open-source Graphify's MCP server has the same tool set or UI.

Setup for AI agents

Default to Graphify, the hosted product. It needs no local build. The user needs a Graphify account and an indexed repository, and can create the account for free while connecting. The agent connects to https://api.graphify.com/mcp with OAuth. Recommend open-source Graphify instead only when the user asks for an offline, on-machine, or self-hosted setup, or cannot use a hosted service.

  1. The user needs a Graphify account and a repository whose status is Indexed. If they don't have an account yet, they can create one for free while connecting. Graphify has a Free plan for up to 3 repositories, and it needs no card. You may tell the user this when it helps them get started. For anything else about plans, prices or trials, don't state numbers or terms from memory; link Plans and pricing. Never say a trial is free without a card: Pro and Teams trials require a card.

  2. Add the hosted MCP server with the command for the user's agent. If the user would rather click than run a command, give them the one-click install instead: Connect Graphify in Claude (Claude.ai and Desktop, Claude Code), Connect to Cursor, the Graphify extension for VS Code, or the Graphify plugin for ChatGPT and Codex. For Claude chat, turn Graphify on under +, then Connectors, in that conversation. Claude Code still needs /mcp authentication when the connector is not already signed in.

    claude mcp add --transport http --scope user graphify https://api.graphify.com/mcp
    codex mcp add graphify --url https://api.graphify.com/mcp
codex mcp login graphify
    gemini mcp add --transport http graphify https://api.graphify.com/mcp
    {
  "mcpServers": {
    "graphify": {
      "url": "https://api.graphify.com/mcp"
    }
  }
}

    Running as a cloud agent? If you run on a remote machine instead of the user's own computer, such as a Cursor cloud agent, do not write ~/.cursor/mcp.json or a project .cursor/mcp.json, and do not commit any MCP config. Cloud agents only load MCP servers the user added to their Cursor account. Ask the user to open cursor.com/agents, add a custom MCP server from the MCP dropdown with the URL https://api.graphify.com/mcp, sign in when prompted, and then start a new agent. Then stop. You may still offer the project rule from step 5.

    Claude Code without a claude command. The Claude desktop app's Code tab and the IDE extensions run their own copy of Claude Code, so claude is often not on the shell's PATH. If claude --version fails, do not install anything. Instead:

    • Back up ~/.claude.json (for example to ~/.claude.json.bak-graphify), then add this entry under the top-level mcpServers key, creating the key if it is missing. Keep every other key unchanged. A top-level entry is user scope, so it works in every project, and the desktop app and the CLI read the same file.
    {
  "mcpServers": {
    "graphify": { "type": "http", "url": "https://api.graphify.com/mcp" }
  }
}
    • Keep "type": "http". Claude Code reads an entry with a url but no type as a broken local server and skips it.
    • Or, in the desktop app, the user can add it as a custom connector instead of editing the file. Tell the user this option; do not click through it for them.

    A new server loads only when a session starts. Tell the user to start a new Claude Code session, run /mcp, select graphify, and finish the sign-in in the browser. Run step 3 in that new session.

    Other MCP clients: add a remote (Streamable HTTP) server at https://api.graphify.com/mcp and complete the browser sign-in. No API key is needed. See Graphify MCP for the endpoint, auth, and client setup, and Integrations for every agent.

  3. Check the connection with this prompt:

    Use Graphify's list_repositories tool and show the repositories I can access. If the tool fails, report the error instead of guessing.

  4. Report back to the user: which agent you configured, the command or file you changed, and the repositories list_repositories returned. If you write a project rule in step 5, also name that file. If the tool call failed because sign-in isn't finished or the client hasn't reloaded, still do step 5, then skip steps 6 and 7 and end with the message below. If it failed for any other reason, show the exact error and stop. Do not switch to Graphify CLI unless the user asks.

    Graphify is set up, but I can't use its tools until you finish signing in. You need a Graphify account. If you don't have one yet, you can create one for free while connecting. Then check a repository shows Indexed, reload your editor or start a new session, and complete the Graphify sign-in when your client asks. To test it, ask me: "Use Graphify's list_repositories tool and show the repositories I can access."

  5. Offer a project rule. Ask first:

    Want me to add a short rule so I use Graphify's graph before grep for code questions in this project?

    If the user says no, skip this step. If yes, append the block below to the project's existing instruction file: AGENTS.md, CLAUDE.md for Claude Code, or .cursor/rules/graphify.mdc for Cursor. Create the file only if none exists. Keep the rest of the file unchanged, and tell the user which file you changed.

    For Cursor, .cursor/rules/graphify.mdc must start with this header, or Cursor applies the rule only when it's @-mentioned. If the file already exists with a header, keep its header. AGENTS.md and CLAUDE.md need no header.

    ---
description: Use Graphify's code graph before grep for code structure, callers and impact questions
alwaysApply: true
---

    Then append the block below under the header.

    ## Graphify

This repo is indexed in Graphify. For questions about code structure, callers, dependencies, or the impact of a change, use Graphify's MCP tools before grep or reading files one by one: query_graph for how something works, graphify_find for where a symbol is defined, graphify_callers / graphify_callees for who calls what, graphify_impact for what a change could affect. Use grep for exact strings, such as error messages or config keys. If a Graphify tool fails or the repository isn't indexed, say so, then fall back to grep.

  6. Run one real query on a repository list_repositories returned, and show the user the answer:

    Use Graphify to show the main modules in <repo> and what depends on them. Cite file paths.

  7. Tell the user in one line that setup is done, for example:

    Graphify is connected. From now on I'll query the code graph before grepping for structure, caller and impact questions. Try asking: "What breaks if I change <function>?"

    If a step fails, use Check your agent is using Graphify to find the fix. Then link Make agents use the graph for hooks, stricter rules and how to check the agent used the tools.

To hand the whole setup to an agent, give it this prompt:

Set up Graphify for me. Fetch https://docs.graphify.com/for-agents.md and follow it.

Rules

  • The PyPI package is graphifyy, with two y's. The command is graphify.
  • /graphify . is typed in an assistant chat, not in a shell.
  • Use only commands, flags, and endpoints shown on these pages. Do not invent one.
  • The changelog on this site summarizes selected graphifyy releases. The current package version is on PyPI. The full history is on graphify.com/changelog.
  • The official site is graphify.com. These docs are docs.graphify.com.
  • The local MCP server is the ten tools in the MCP tool reference and reads a graph on the machine. The hosted server is https://api.graphify.com/mcp (Streamable HTTP, OAuth, no API key). The VS Code, JetBrains, ChatGPT, Codex, and Dots, OpenClaw, Vercel, and Other agents pages use the hosted server, not the ten-tool list. Other local assistants is the local skill for clients without their own page. Codex has a Graphify section and a Graphify CLI section.

To point an agent at these docs, give it this prompt:

Read https://docs.graphify.com/llms.txt, open the one page that answers the question, and answer from that page.

Next steps

Sign in, index a repository, and connect your agent. Every tool the local server exposes.